Consider mkdocs or sphinx instead of jekyll

[bradyt]

I forked your project here, it is awesome, just having access to the docs as markdown is a big win for me. I noted the jekyll site, and wondered if mkdocs could improve the experience. I realize there is an attempt to use Sphinx, I'm not sure if they can improve beyond current implementation. If I understand correctly, one limitation of readthedocs theme is, it's limited to depth two. Not sure if that is relevant here. I have a prototype of a MkDocs version of your site, at https://bradyt.github.io/beancount-docs/. I suspect it would be trivial to add an "edit page" button. I'm not sure yet how to fix rendering of in-page table of contents into left pane (or top of page for narrow screens). I'm not sure yet how to fix the linking of images.

~(I had some errors running crawl.py, but hoping to ignore that until I really have to spend time on it.)~

[xuhcc]

I never used mkdocs before, but overall it looks good.

In addition to missing images, I also noticed that it didn't render footnotes (here, for example https://bradyt.github.io/beancount-docs/24_beancount_design_doc/). If we will be able to resolve these issues, I would prefer mkdocs, because it's written in python :)

[bradyt]

Okay, so I've got some prototype solutions for toc and images, and I think footnotes was easily solved by enabling an extension.

footnotes

See https://github.com/bradyt/beancount-docs/commit/c2b2b933efec27888b849b225f73f8463f949e89. See working footnote at "And then shortly after I started on Beancount^1." at https://bradyt.github.io/beancount-docs/01_command_line_accounting_in_context/#why-am-i-so-excited.

toc

(You didn't emphasize this as blocking, but I think it really helps with navigation.) One solution for enabling MkDocs's toc, is to delete the tags from headings. I did this manually for the first two pages just to show the result. If this can be automated by modifying the existing script, or some post generate script, I'm not sure what we can do yet. See https://github.com/bradyt/beancount-docs/commit/870e6739a5902c7c6661e6c15ab8df5699579cd4. See functioning toc at https://bradyt.github.io/beancount-docs/ and https://bradyt.github.io/beancount-docs/01_command_line_accounting_in_context/.

images

The issue with images seems to be that the webpage is actually converted to an index.html in the same subdirectory, so perhaps either the image url should be made absolute, or truncated to be relative starting with media/. See https://github.com/bradyt/beancount-docs/commit/18fed4e3eaabf4102fa4cda600529f2cb257fb7b or https://github.com/bradyt/beancount-docs/commit/3e50d2a76fb3e92f1fcc4a2fc04e5db3204ef070. See a working image at https://bradyt.github.io/beancount-docs/01_command_line_accounting_in_context/#how-the-pieces-fit-together (may need to clear cache). Is this easily fixed by tweaking the generate script?

[xuhcc]

Anchors in headings were added in b156647c18b17fe816bf9e74968b10b03c7dc3dd, I think you can simply revert this commit.

[xuhcc]

Changing image paths is more complicated, because they are produced by pandoc itself. Maybe we can just add / to each path in filter.py.

[xuhcc]

Try this patch:

diff --git a/filter.py b/filter.py
index 66b631d..5965896 100644
--- a/filter.py
+++ b/filter.py
@@ -7,6 +7,7 @@ from panflute import (
     stringify,
     BlockQuote,
     CodeBlock,
+    Image,
     Header,
     LineBreak,
     Link,
@@ -113,6 +114,9 @@ def action(elem, doc):
         # Remove unnecessary leading tabs from code blocks
         elem.text = re.sub(r'^\t', '', elem.text, flags=re.MULTILINE)

+    elif isinstance(elem, Image):
+        elem.url = '/' + elem.url
+

 def main(doc=None):
     return run_filter(action, prepare=prepare, doc=doc)

[bradyt]

Oh, I was in my own little world there. When the site is live, the relative path seemed to work better, truncating to media/.... So I just used Emacs's dired's Q which does recursive regexp replaces. The live site now has all working images, toc, etc.

Maybe we can tweak that assignment above to strip off the first part of path.

[bradyt]

Aha, I think it works with,

-        elem.url = '/' + elem.url
+        elem.url = './' + elem.url

[bradyt]

If this all looks fine, I'll rebase and file a draft as pull request?

I'll remove the markdown line wrapping, as I don't see that yourself or beancount author prefer it.

[xuhcc]

New docs has been deployed to https://xuhcc.github.io/beancount-docs/