Terkwood / emanote

WIP: Spiritual successor to neuron, based on Ema.

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: Nearly 1.0. HTML templates are yet to be finalized (so do not customize your templates just yet).

Installing and using

# Install (`cachix use srid` for cached binaries)
nix-env -if https://github.com/srid/emanote/archive/refs/heads/master.tar.gz
# Or, from the Git repo: nix-env -if ./default.nix

# Run live server (PORT is optional)
cd /path/to/notebook
PORT=8001 emanote

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

Examples

Emanote is suitable for creating ...

• ... project sites, such as: ema.srid.ca (view source).
• ... wiki sites, such as: Unofficial r/TheMotte Wiki (view source)
• ... personal website/blogs, such as: www.srid.ca (view source)
• ... Zettelkasten sites (Neuron-like), such as: woke.zettel.page (view source)

Developing

Emanote is written in Haskell. Thanks to Nix, this repository is pre-configured to provide a delightful development experience 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 (Expect it to download and build a bunch of things the first time)
• Open the repository 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 dev version Emanote on ./docs, then navigate to http://localhost:9010/
  • Changing the Haskell sources will recompile and reload this instance automatically.

All but the final step need to be done only once. See architecture.md for a high-level overview of the codebase.

Discussion

To discuss the emanote project, join Matrix or post in GitHub Discussions.

Tasks

(Archived/Done tasks further below)

Current

Backlog,

• Finally, tests!
  • URL parsing (.md and wiki-links) and route encoding/decoding
  • Metadata overriding
• neuron query equivalent?
• Consistent ordering of notes in sidebar, index, query listing, backlinks
  • .timeline query in particular should be sort by date
  • calendar children shoiuld be sorted by name (thus day), just as other notes?
• fsnotify: reliably handle directory renames/ moves
  • Straightforward to do using unionMount's OverlayFs?
  • If nothing, restart mount on such events.
• RSS

Before public release

• Finalize Heist variables/structures and template locations
  • Try Heist.Compiled
• Finalize Tailwind styling of Pandoc (esp. margins)

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.
• apply prismJS on live server refresh?
• Add fsnotify watcher for default template files (etc), but only in ghcid mode
• Sidebar: expand-by-default on per-tree basis, by enabling it on yaml or frontmatter
• Directory routes (allow $dir.html even if $dir.md doesn't exist)
• 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

Milestone (www.srid.ca),

• Footnotes
• Custom route slugs srid#42
• Blog post friendly
  • Queries
    • Query by tag (in code block)
    • Date in queries (requires Heist withJson changes)
      • Hierarchical tags?
• Theme touches
  • Timeline query styling (use CSS grid)
  • Ugly footnote empty line with multi-block notes
  • Final website look (not boring)
• 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 R to accomodate them all, and ditch Either FilePath
  • Try OpenUnion to make Note/Ref's route field polymorphic over file type
• Embedding / Filtering / Transforming / etc
  • Link embedding: support ![[]] of Obsidian? https://help.obsidian.md/How+to/Embed+files
    • Consider designing this in the larger context of Pandoc splice with customizable rendering
      • Including wiki-links (thus supplanting rewriteLinks)
      • Including queries (see below)
    • Also consider non-Obsidian formats, `![[program.hs:2-13]]
  • Queries and results embed (see below)
  • WikiLink embedding for note should use .tpl layout
• Zettelkasten / Graph considerations (a la neuron),
  • Uplink tree srid#25
  • Reinstate Neuron look & feel (or just improve on it; make Emanote's note template distinct-looking, and an improved version of neuron's)