carliros / 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: Partially implemented enough to be usable for certain use-cases (see examples below). HTML templates are yet to be finalized (so do not customize your templates just yet), and most importantly folgezettel graph and visualization needs to be implemented to act as true neuron replacement (see tasks below).

Installing and using

# Install (`cachix use srid` for cached binaries)
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

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: coming soon

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

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 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
  • 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,

• RSS
• 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?
• dd styling
• Table styling
• Directory routes (allow $dir.html even if $dir.md doesn't exist)
  • Display children inline?
• fsnotify: reliably handle directory renames/ moves
  • Straightforward to do using unionMount's OverlayFs?
  • If nothing, restart mount on such events.
• 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
• neuron query equivalent?
• 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

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
• Finalize Heist variables/structures and template locations

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.

Milestone (notes.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)