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.

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 mkdocs.yml as:

nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs:
    - borgs/index.md
    - Bar: borgs/bar.md
    - Foo: borgs/foo.md

plugins:
  - section-index

Unconnected thoughts⚑

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.
https://www.gwern.net/About#confidence-tags
https://www.gwern.net/About#importance-tags
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 tbd tag 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.xml that 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