mm-docs-template
MkDocs

mm-docs-template | MkDocs | |
---|---|---|
1 | 118 | |
9 | 19,888 | |
- | 1.1% | |
6.1 | 7.9 | |
8 months ago | 3 months ago | |
PowerShell | Python | |
- | BSD 2-clause "Simplified" License |
Stars - the number of stars that a project has on GitHub. Growth - month over month growth in stars.
Activity is a relative number indicating how actively a project is being developed. Recent commits have higher weight than older ones.
For example, an activity of 9.0 indicates that a project is amongst the top 10% of the most actively developed projects that we are tracking.
mm-docs-template
-
Why Your Company's Documentation Sucks
This view is too much simplified. If docs where tree vs graph we would probably have at least some orgs doing it right, while there are literarily almost zero.
Some of the important aspects of good documentation is:
1. Narrative style. You can't do ad hoc whatever wherever and call it a day. Most people don't have it and many are quite illiterate IMO. You need to practice this and most engineers don't like that. Hell, even most seniors don't like writing tickets IME which take almost the same time as putting garbage on Slack. I created templates on both GH and GL and almost nobody uses them even tho you don't need to think about anything but follow few rules.
2. Its quite hard to know what level of detail to put in documentation. You need a lot of experience for this - put to much, and it gets quickly outdated, put too little, and it doesn't convey much. Good documentation exists on multiple levels - as bunch of markup files "on the spot", as formal hi and low level documentation and also those are usually affecting different target groups so you actually need to design docs.
3. Documentation is a service. It has source code, build procedure, automatic link checking, export to bunch of format, crosslinks, variables, macros, configuration for different environments, abbreviations, definitions. Its quite hard to get it right. After years of struggle on different projects I finally created my own stuff [1] that I use on all projects, for docs spanning 50-500 pages. I maintain that for years now, constantly (so yeah, its a job).
[1]: https://github.com/majkinetor/mm-docs-template
MkDocs
-
How to Create and Publish a Python Package on PyPI 🐍
The original mkdocs uses a Python package for its installer, so you can just pip install mkdocs, mkdocs new ., and then mkdocs build to convert markdown files into HTML.
-
Docusaurus – Build optimized websites quickly, focus on your content
If you don't like to run javascript outside of a browser, MkDocs is a great Python-based alternative: https://www.mkdocs.org/
-
Why I Prefer RST to Markdown
I like Markdown because it's simple and doesn't give me that many headaches.
You know what I don't like? HTML, for user submitted content in particular. The mess I've seen, after someone opted for using HTML for messages in a system, because that's what JS based editors were available for at the time. Endless need to work against XSS, with more and more incremental updates needed to the sanitization logic, some of which broke the presentation of the data in the DB.
Never again. Markdown, BBCode, anything but that.
As for docs? Currently just some Markdown, because that's what GitHub, GitLab, Gitea and others all know how to render.
Maybe something like https://www.mkdocs.org/ for the more standalone use cases.
-
Why Docs-as-Code is the Key to Better Software Documentation
Developing the documentation website using an open-source static site generator like Sphinx or MkDocs to build the files locally through the command line, rather than using a commercial program.
- I am stepping down from MkDocs
-
Alternatives to Docusaurus for product documentation
MkDocs is BSD-2-Clause licensed and has a vibrant community; GitHub Discussion is used for questions and high-level discussion, while the Gitter/Matrix chat room is used to discuss less complex topics. These communities provide essential resources and support.
- Ask HN: Tips to get started on my own server
-
Enhance Your Project Quality with These Top Python Libraries
MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.
-
Top 5 Open-Source Documentation Development Platforms of 2024
MkDocs is a popular static site generator designed explicitly for building project documentation. Its minimalist approach, flexibility, and ease of use have made it a favorite among developers and ideal for non-technical users.
What are some alternatives?
mm-docs - Documentation system in a docker container using mkdocs, plantuml and many more
sphinx - The Sphinx documentation generator
log4brains - ✍️ Architecture Decision Records (ADR) management and publication tool
pdoc - API Documentation for Python Projects
Doxide - Modern documentation for modern C++. Configure with YAML, output Markdown, post-process with Material for MkDocs.
DocFX - Static site generator for .NET API documentation.
pydoc-markdown - Create Python API documentation in Markdown format.
Hugo - The world’s fastest framework for building websites.
docs - The documentation for Firefly III
BookStack - A platform to create documentation/wiki content built with PHP & Laravel
Optic - OpenAPI linting, diffing and testing. Optic helps prevent breaking changes, publish accurate documentation and improve the design of your APIs.
Docusaurus - Easy to maintain open source documentation websites.
