Website publishing - tools and options

Jamstack

https://jamstack.org/

Issues with maintaining notes without publishing

1. With pure emacs approach, working with notes has become a one-way street. Notes are going into the repo. But they are not being revisited, revised, reviewed, remembered. Publishing gives more value to the notes.
2. The org documents are dependent on emacs. Without emacs, it is difficult to get value out of them. This goes against the principle of not needing “special software” to view notes. The value of notes should not be detracted by a particular software. The notes should be accessible (at least, in a Read only way) no matter where you are in the world. If you have a browser, you should be able to view the notes. This is where publishing comes in.

Things to consider when considering a publishing option for the org pages

1. The content needs to look good
2. Has to support table of contents
3. Has to work with images
4. Has to work with code snippets
5. Automatic publishing into markdown files (nice to have)
6. Automatic publishing of the markdown files into public (nice to have)
7. Automatic publishing of the markdown or the public folder to a website
8. Must support search feature
   1. Search by text (exact match)
   2. Seach by node names
9. Must support Tag and Backlink features
   1. Must show Tags
   2. Must show backlinks
10. Showing the Tags and Backlinks in a graphical view is an added advantage.

Options for publishing

Pure GitHub approach for maintaining the personal wiki

Maintaining personal-wiki org files in just a GitHub repository:

Advantages

1. Search capability for content from the pages.

Disadvantages

1. Navigation between the links is not good. The links in a page are not clickable/navigatable. They are not hyperlinks. So the primary advantage with linking pages is lost when looking at them in GitHub.

GitHub pages

https://pages.github.com/

Disadvantages

1. The GitHub repository has to be public and the published github.io page will also be public.
2. We have to use the template that comes with it. Limits our choices when it comes to customization.

mdBook

https://rust-lang.github.io/mdBook/index.html

cargo install mdbook

mdbook init finance-notes

mdbook serve --open

We need to copy the markdown into src folder and update Summary.md file for them to show up in the website.

1. Uses Rust
2. Haven’t tried it personally

Next.js for static websites

org-mode + org-roam + Hugo + GitLabs

org-mode + org-roam + Hugo + Hugo themes + github/gitlab

org-mode + org-roam + quartz + gitlab/github

jekyll

Off to a bad start

Tried to follow the instructions from this page: https://jekyllrb.com/docs/

First, nothing would run without adding ruby to the path like this:

export PATH=/home/explorer436/.local/share/gem/ruby/3.3.0/bin:$PATH

After that, I tried running the command to set-up a jeckyl site and I ran into This error:

[explorer436@explorer436-p50-20eqs27p03 temp]$ jekyll new myblog
<internal:/usr/lib/ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require': cannot load such file -- erb (LoadError)
Did you mean?  drb
        from <internal:/usr/lib/ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require'
        from /home/explorer436/.local/share/gem/ruby/3.3.0/gems/jekyll-4.4.1/lib/jekyll/commands/new.rb:3:in `<top (required)>'
        from <internal:/usr/lib/ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require'
        from <internal:/usr/lib/ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require'
        from /home/explorer436/.local/share/gem/ruby/3.3.0/gems/jekyll-4.4.1/lib/jekyll.rb:13:in `block in require_all'
        from /home/explorer436/.local/share/gem/ruby/3.3.0/gems/jekyll-4.4.1/lib/jekyll.rb:12:in `each'
        from /home/explorer436/.local/share/gem/ruby/3.3.0/gems/jekyll-4.4.1/lib/jekyll.rb:12:in `require_all'
        from /home/explorer436/.local/share/gem/ruby/3.3.0/gems/jekyll-4.4.1/lib/jekyll.rb:188:in `<top (required)>'
        from <internal:/usr/lib/ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require'
        from <internal:/usr/lib/ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require'
        from /home/explorer436/.local/share/gem/ruby/3.3.0/gems/jekyll-4.4.1/exe/jekyll:8:in `<top (required)>'
        from /home/explorer436/.local/share/gem/ruby/3.3.0/bin/jekyll:25:in `load'
        from /home/explorer436/.local/share/gem/ruby/3.3.0/bin/jekyll:25:in `<main>'

Didn’t spend any more time on it after that.

TODO

1. Build a full graph of the mindmap from org-roam-db. https://hugocisneros.com/blog/my-org-roam-notes-workflow/#publishing

Tags

1. Steps for building content folder from org files using org-roam
2. Hugo themes and customizations
3. Hosting platforms