alnoda/mkdocs-magicspace repository overview

⁠MkDocs-MagicSpace

MkDocs-MagicSpace is an all-in-one tool, carefully crafted to make the development of gorgeous documentation websites like this one⁠ as easy as possible.

⁠Why this images

If want a ready tool to develop and build beautiful doccumentation websites with only Markdown.

⁠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-8035:8020-8035 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.

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
• Cronicle⁠ - task scheduler and runner, with a web based front-end UI. It handles both scheduled, repeating and on-demand jobs, targeting any number of worker servers, with real-time stats and live log viewer.
• Static File Server⁠ - view any static html sites as easy as if you do it on your local machine. Serve static websites easily.
• Ungit⁠ - rings user friendliness to git without sacrificing the versatility of it.
• MkDocs⁠ - create awesome documentation for your project with only markdown.
• Midnight Commander⁠ - Feature rich visual file manager with internal text viewer and editor.
• Process Monitor⁠ - Monitor running process and resource utilization.
• Quicklaunch UI with getting started tutorial

Image is built from Ubuntu 20.4 with the additional CLI apps

• Zsh⁠, Oh my Zsh⁠
• Python 3, Pip
• Node/nodeenv
• curl, wget, telnet, jq
• Git: git, git-flow, lazygit
• File browsers: mc, xplr
• Text editors: nano, vim, mcedit
• System monitors: ncdu, htop, glances, vizex
• Process Control: supervisord
• Job scheduler: cron

⁠Docs

See our guides on getting started⁠, extended Markdown tutorials⁠ and advanced features⁠.