Build your own Digital Garden
This page is an early version of a WIP
If you don't want to start from scratch, you can fork the blue book and start writing straight away.
Enable clickable navigation sections⚑
By default, mkdocs doesn't let you to have clickable sections that lead to an index page. It has been long discussed in #2060, #1042, #1139 and #1975. Thankfully, oprypin has solved it with the mkdocs-section-index plugin.
Install the plugin with
pip install mkdocs-section-index and configure your
nav: - Frob: index.md - Baz: baz.md - Borgs: - borgs/index.md - Bar: borgs/bar.md - Foo: borgs/foo.md plugins: - section-index
- Set up ci with pre-commit and ALE.
- Create a custom commitizen changelog configuration to generate the rss entries periodically and publish them as github releases.
- If some code needs to be in a file use:
!!! note "File ~/script.py" ```python print('hi') ```
- Define how to add links to newly created documents in the whole wiki.
- Deploy fast, deploy early
- Grab the ideas of todo
- Define a meaningful tag policy.
Decide a meaningful nav policy.
- How to decide when to create a new section,
- Add to the index nav once it's finished, not before
- Use the
tbdtag to mark the articles that need attention.
- Avoid file hardcoding, use mkdocs autolinks plugin, or mkdocs-altlink-plugin if #15 is not solved and you don't need to link images.
- Use underscores for the file names, so the autocompletion feature of your editor works.
- Add a link to the github pages site both in the git repository description and in the README.
- Use Github Actions to build your blog.
- Make redirections of refactored articles.
- The newsletter could be split in years with one summary once the year has ended
- I want an rss support for my newsletters, mkdocs is not going to support it, so the solution is to use a static template
rss.xmlthat is manually generated each time you create a new newsletter article. I could develop a plugin so it creates it at build time.
- Use of custom domains
- Material guide to enable code blocks highlight: From what I've seen in some github issue, you should not use it with codehilite, although you still have their syntax.
- User Guide: Writing your docs
- Example of markdown writing with Material theme and it's source
- Add revision date
- Add test for rotten links, it seems that htmltest was meant to be faster.
- Adds tooltips to preview the content of page links using tooltipster. I only managed to make it work with internal links and in an ugly way... So I'm not using it.
- Plugin to generate Python Docstrings
- Add Mermaid graphs
- Add Plantuml graphs
- Analyze the text readability
Create a local server to visualize the documentation⚑
Last update: 2021-05-25