serra/sphinx-with-markdown

Markdown-native toctrees

Opened this issue · 0 comments

kousu commented

Hi! I found your research on SO. Thanks so much for trail-blazing this. I was getting ready to figure out how to implement your solution when I noticed that https://sphinx-themes.org/sample-sites/sphinx-book-theme is entirely written in markdown. Here's how they seem to have done it:

  • in index.md (instead of index.rst) add
  • a code block tagged with type toctree:
 ```{toctree}
 :maxdepth: 1
 :caption: Topic Areas
 
 tutorials/get-started
 customize/index
 content-blocks
 notebooks
 launch
 ``

We can see the full working docs at https://github.com/executablebooks/sphinx-book-theme/tree/master/docs