Skip to content

Get started

Getting started with MkDocs-MagicSpace is extremely easy. It already has everything needed: tools, packages and extensions for the Extended Markdown (and more advanced features), documentation and tutorials, and even a boilerplate.

(Let's assume that you have started MkDocs-MagicSpace on your laptop or remote server. If not, read the Docs first)


MkDocs-MagicSpace is based on the popular open-source static site generator MkDocs.

MkDocs project - is a folder in your MkDocs-MagicSpace workspace, which must have the following minnimal structure

mkdocs.yml    # The configuration file.
docs/  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

When you cd into the MkDocs project folder, 2 commands to remember:

  • mkdocs serve -a<PORT> - Start the live-reloading docs server.
  • mkdocs build -d <OUTPUT_PATH> - Build the documentation site.

For the full documentation visit

Create your Mkdocs project

MkDocs-MagicSpace contains a boilerplate documentation project, which you can use to get started. It is the same project, that serves the workspace UI, the one you might use it to document the workspace itself. Simply copy it to the project folder, and customize it as you wish.

Open MkDocs-MagicSpace terminal, and execute

cp -r /home/docs /home/project/my-docs

Great! You have started your own documentation project!

Start the Mkdocs development server on any of the free ports in the port range you have provided for the workspace

cd /home/project/my-docs; mkdocs serve -a

Open your Browser on localhost:8030

Tricky ports

If you have used the default port range to run the MkDocs-MagicSpace (8020-8035:8020-8035) then the internal port you use to run the mkdocs server (mkdocs serve -a is the same as the external port - 8030. If you have used different port ranges, you will need to understand to which external port, the internal ports are mapped. Let's imagine we used different port range to start MkDocs-MagicSpace, for example, 9070-9085:8020-8035. In this case, internal port 8030 will map to external port 9080. So when you start the mkdocs server (in the workspace terminal) on port 8030 (as in mkdocs serve -a, then you need to open in your browser http://localhost:9080

Customize boilerplate

The boilerplate you have copied to start your own project contains pages you might not need. You can modify them, or simply delete and create your own.

When you work with Mkdocs, you create websites using Markdown. Mkdocs renders .md from the docs subfolder of the project, and you specify which .md files to show (and in which order) in the mkdocs.yml file in the root of the project folder.

Let's delete all existing markdown files from the boilerplate folder. To do this you can use Filebrowser, Theia IDE, M.Commander, or just terminal. The easiest way - is to use filebrowser, which is well-suited to manipulate workspace filesystem, and to easily exchange files and folders between the outer environment and the workspace. Filebrowser provides the same user experience, no matter if the workspace is running on your laptop, or launched in the cloud server).


It is convenient to use IDE for this too 👇


We need to remove references to these markdown files from the mkdocs.yml file too


# ===========================================================
# ===========================================================

  - Home: pages/home/
  - About:
  - Get started:
  - Showcase:

Let's create our own new markdown file in the same docs subfolder 👇


And add a reference to this markdown file in the mkdocs.yml file


# ===========================================================
# ===========================================================

  - My Project:
Save Ctrl+S the files you have created and modified. Mkdocs server will reload automatically, and in couple of seconds you will see that new changes are applied.