alnoda-workspaces/workspaces/mkdocs-magicspace/README.md

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.

Known Mermaid problem after major update (fix pending)

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-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.

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
• project docs

Demo

Demo: MkDocs MagicSpace