mkdocs-multirepo

A bit like monorepo, but keeps MkDocs projects separate.

Note: This tool is in beta.

Use Case

This CLI tool allows you to build multiple MkDocs documentation projects and generate a landing page for them:

Landing Page Example

Unlike monorepo, multirepo doesn't merge projects into one.

Instead, multirepo adds the MkDocs projects as Git submodules, builds them individually, and generates an HTML landing page based on a template file.

This has a number of advantages, for example:

Keeps the individual mkdocs.yml settings of each project. This means that, e.g., each project can have its own color set or theme.
Avoids problems with relative paths in the projects.
Keeps search indexes small instead of creating a giant merged index.

Installation

Install via pip install mkdocs-multirepo.
Create a directory and put two files named config.yml and index.tpl in it.
Configure the files as described below.
Change to the directory created in step 1.
Run git init.
Run mkdocs-multirepo --init.

Usage

Usage: mkdocs-multirepo [OPTIONS]

Options:
  --init      Initialize the repos as Git submodules.  [default: False]
  --update    Update the repos, i.e., the Git submodules.  [default: False]
  --build     Build all MkDocs projects and generate the landing page.
              [default: False]

Configuration

Sample Project

See mkdocs_multirepo/demo for a sample project.

Note: Search is not functional. You must implement it yourself, e.g., using Docsearch.

config.yml

Use the config.yml file to configure the build process. Example:

repos:
  - name: repo-1
    title: My Repository 1
    image: images/icon-repo-1.png
    url: https://github.com/giansalex/mkdocs-sample.git
    branch: master
  - name: repo-2
    title: My Repository 2
    image: images/icon-repo-2.png
    url: https://github.com/hristo-mavrodiev/mkdocs-sample.git
    branch: master
    index_html: install/index.html
element_id: multirepo
target_dir: site
repos_dir: src
index_tpl: index.tpl
extra_files:
    - styles.css
    - images/search.svg

Each entry under repos configures an MkDocs project:

name: Used to create the Git submodule directory and also the output directory within target_dir.
title: Text for the landing page list item.
image: Image for the landing page list item.
url: URL of the repository.
branch: Branch of the repository. Default: empty (which is master for most repositories).
mkdocs_dir: Directory (within repo) where the MkDocs directory structure is located. Default: ..
mkdocs_config: MkDocs config file used during mkdocs build. Default: mkdocs.yml.
index_html: Index HTML file for this repository. Default: index.html.
pdf: Link to a PDF file within the repository, if desired.
element_id: ID of the DOM element on the landing page where the links to this repo project should be created. Default: use general setting (see below).

Additionally, the following general settings are available:

element_id: ID of the DOM element on the landing page where the links to the projects should be created. Default: multirepo.
target_dir: Output directory. Default: site.
repos_dir: Target directory for repositories (submodules). Default: repositories.
extra_files: Additional files to be placed in the output directory.
index_tpl: Path to the landing page template (see below). Default: index.tpl.

index.tpl

Use the index.tpl file to configure the landing page. Example:

<html>
    <head>
        <title>Multirepo Demo Page</title>
        <link rel="stylesheet" type="text/css" href="https://github.com/wilhelmer/mkdocs-multirepo/blob/master/styles.css">
    </head>
    <body>
        <section id="multirepo"></section>
    </body>
</html>

The template must be written in HTML and must contain a node with an ID called "multirepo" or as defined using the element_id setting.

From this template, a landing page named index.html will be generated and placed into target_dir.

Sample output:

<html>
    <head>
        <title>Multirepo Demo Page</title>
        <link href="https://github.com/wilhelmer/mkdocs-multirepo/blob/master/styles.css" rel="stylesheet" type="text/css" />
    </head>
    <body>
        <section id="multirepo">
            <ul>
                <li><a href="https://github.com/wilhelmer/mkdocs-multirepo/blob/master/repo-1/index.html"><img src="https://github.com/wilhelmer/mkdocs-multirepo/raw/master/images/icon-repo-1.png" /><span>My Repository 1</span></a></li>
                <li><a href="https://github.com/wilhelmer/mkdocs-multirepo/blob/master/repo-2/01_index.html"><img src="https://github.com/wilhelmer/mkdocs-multirepo/raw/master/images/icon-repo-2.png" /><span>My Repository 2</span></a></li>
            </ul>
        </section>
    </body>
</html>

wilhelmer / mkdocs-multirepo

readme