mirror of
https://github.com/bluxmit/alnoda-workspaces.git
synced 2024-08-04 13:01:48 +12:00
.. | ||
docs | ||
examples/mkdocs-material | ||
img | ||
mkdocs | ||
Dockerfile | ||
mkdocs-requirements.txt | ||
README.md | ||
settings.json |
MkDocs workspace
Containerized environment which helps to develop complex and awesome-looking documentation websites.
Create docs from all your GitHub, GitLab and Bitbucket repositories, automate periodic builds.
Why
- If want a ready tool to develop beautiful doccumentation websites.
- You need a tool to automate and schedule builds of docs from many repositories.
Why documentation websites with MkDocs
Why create separate documentation websites? And if so, why MkDocs?
- MkDocs website with beautiful themes looks much better than any readme file. The resulting documentation website looks professional and awesome.
- MkDocs adds text search to your documentation website.
- In the case of closed-source software, sharing readme files from the git repository with external users is not an option.
- Github does not render beautiful extended markdown features like admonitions, tabs, etc. Neither renders diagrams, formulas, swagger docs, or notebooks.
- Using MkDocs-MagicSpace you create documentation from the same markdown readme files you have in your repo together with the code. And you can create a unified documentation website from multiple repositories in Github, GitLab, Bitbucket.
- You can add such features as Google Analytics, multi-language localization.
Start
docker run --name space-1 -d -p 8020-8040:8020-8040 alnoda/mkdocs-magicspace
and open localhost:8020 in browser.
Features
MkDocs:
- MkDocs - a fast, simple and downright gorgeous static site generator that's geared towards building project documentation.
- Material for MkDocs - gorgeous theme for MkDocs.
- PyMdown Extensions - add even more cool features of the extended markdown: sub- and superscripts, keys, magic links, sane headers etc.
- Mkdocs-macro plugin - add variables and macros written in Python!
- Mkdocs-multirepo-plugin - import docs directly from git repositories.
- Mkdocs-monorepo plugin - build multiple documentation folders in a single Mkdocs. Designed for large codebases.
- MkDocs Newsletter - show the changes of documentation repositories in a user friendly format, at the same time that it's easy for the authors to maintain.
- Mkdocs-mermaid2-plugin - renders textual graph descriptions into Mermaid graphs (flow charts, sequence diagrams, pie charts, etc.).
- Pygments - a generic syntax highlighter suitable for use in code hosting, forums, wikis or other applications that need to prettify source code, with over 500 languages and other text formats.
- Mkdocs-include-markdown-plugin - include Markdown files completely or partially, and include files of any type.
- Mkdocs-table-reader-plugin - directly insert CSV files as tables in your website.
- Mkdocs-video - Include viedeos in the documentation.
- many other plugins
Dev tools:
- Eclipse Theia - open source version of popular Visual Studio Code IDE. Theia is trully open-source, has VS-Code extensions and works in browser. This means it can run inside a docker container on local machine or in cloud. A lot of beautiful color themes and many common plugins are already installed to save time.
- Terminal - secure browser-based terminal.
- FileBrowser - manage files and folders inside the workspace, and exchange data between local environment and the workspace
- Ungit - rings user friendliness to git without sacrificing the versatility of it.
- Ubuntu 20.4 with the following CLI apps
Docs
See our guides on
Demo
Demo: MkDocs MagicSpace