emanote

WIP: Spiritual successor to neuron, based on Ema.

Create beautiful websites -- such as personal webpage, blog, wiki, Zettelkasten, notebook, knowledge-base, documentation, etc. from future-proof plain-text notes and arbitrary data -- with live preview that updates in real-time.

Project Status: Alpha status, but usable for generating documentation sites (see examples below). HTML templates are yet to be finalized. More features are being worked on (see tasks below).

Installing and using

# Install
nix-env -if ./default.nix

# Run live server
PORT=8001 emanote -C /path/to/notebook

# Generate static files
mkdir /tmp/output
emanote -C /path/to/notebook gen /tmp/output

Examples

• ema.srid.ca (generated from these sources).
• Haskell KB (generated from these sources)

Hacking

To develop with full IDE support in Visual Studio Code, follow these steps:

• Install Nix & enable Flakes
• Run nix-shell --run haskell-language-server to sanity check your environment
• Open as single-folder workspace in Visual Studio Code
  • Install the workspace recommended extensions
  • Ctrl+Shift+P to run command "Nix-Env: Select Environment" and select shell.nix. The extension will ask you to reload VSCode at the end.
• Press Ctrl+Shift+B in VSCode, or run bin/run (bin/run-via-tmux if you have tmux installed) in terminal, to launch the Ema dev server, and navigate to http://localhost:9010/

All but the final step need to be done only once.

Tasks

Current

Before tests (tasks impacting the larger architectural context in code base),

• Interlude(architecture): a layer between ema and emanote
  • source -> target file transformation with routing
  • examples
    • source: .md, .org, static files, ..
    • output: .rss/.xml
• WikiLink: allow linking to non-HTML files.
  • Refactor Route to accomodate them all, and ditch Either FilePath
• Embedding / Filtering / Transforming / etc
  • Link embedding: support ![[]] of Obsidian? https://help.obsidian.md/How+to/Embed+files
    • Have rewriteLinks pass "title" to WikiLink parser, and have it return WikiLink Video (as distinct from WikiLink Md)
      • For embed flag, make that WikiLink Embed Video (vs WikiLink (Conn Folge) Md)
    • That, or do it from <PandocLink> style, in rpBlock by decoding "title" attr.
    • Also consider non-Obsidian formats, `![[program.hs:2-13]]
  • Queries and results embed
• Generation of pages with no associated Markdown
  • eg: Pagination ala https://web.dev/authors/ | https://web.dev/how-we-build-webdev-and-use-web-components/#collections
• neuron UpTree?
  • ixset + path finding traversal
  • rendering design: where to place? esp. in relation to sidebar?
• Finally, tests!
  • URL parsing (.md and wiki-links) and route encoding/decoding
  • Metadata overriding

To triage,

• apply prismJS on live server refresh?
  • Hack on <script class="ema-rerun">?
• emanote gen should generate $dir.html even if $dir.md doesn't exist.
• Proper footnote styling: take Tufte style (sidebar refs) into consideration
• BUG: raw HTML doesn't work (eg:
• emanote init to allow editing default templates/yaml
• Add fsnotify watcher for default template files (etc), but only in ghcid mode
• Allow overriding baseUrl in CLI: emanote gen --baseUrl=srid.github.io/foo
• Sidebar: expand-by-default on per-tree basis, by enabling it on yaml or frontmatter
• neuron query equivalent?
• Heist Pandoc splice: allow custom "class library" with hierarchy:

  <Pandoc>
    <Custom>
      <Popout class="px-1 font-serif rounded bg-pink-50" />
      <!-- Hierarchical styling? -->
      <Warning class="px-1 rounded bg-gray-50">
        <Header>
          <h2>class="text-xl font-bold"</h2>
        </Header>
      </Warning>
    </Custom>
  </Pandoc>
  

Before public release

• Finalize in HTML templating: heist vs a more popular one?
  • Probably gonna take the heist trade-off, given the ability to customize breadcrumbs/sidebar/pandoc HTML

Archived Tasks

Initial MVP,

• Wiki-links
• Splice work
  • Make sidebar tree a splice
  • Make breadcrumbs a splice
    • Requires supporting arbitrary HTML in node children
  • Make pandoc view a splice
• Backlinks
  • Using ixset
• Report error on web / CLI on markdown parse failure (generally on any error)
• .emanote/templates/settings.yml - to pass global vars (theme, site-title) as-is
• Use default templates and metadata if none exist
  • Load templates from cabal data-files by default
  • Do the same for index.yaml (then test on haskell-kb)
• Use default static files (favicon.svg) for those that do not exist
• Finish Pandoc AST rendering (address Unsupported)
• Add docker image
• Milestone: Make ema.srid.ca an emanote site
  • Bugs and blockers
    • /start.md - the .md breaks links
    • workaround raw html bug (see below) using video raw format
    • "Next" styling, via class map in .yaml
  • docs: adjust tutorial for new ema-template
  • ema-docs: replace with ema-template
• Tailwind CDN: replace with windi workflow for faster page load, or use Twind shim
• Avoid "Ema - Ema" kind of title. Pass ifIndexRoute splice?
• BUG: /Haskell.org (with dot in it) crashes ema dev server
• Milestone: ./emanote -C ~/code/haskell-knowledge-base should just work.