Getting started¶

Installation¶

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'ru.vyarus:gradle-mkdocs-plugin:2.3.0'
    }
}
apply plugin: 'ru.vyarus.mkdocs'

OR

plugins {
    id 'ru.vyarus.mkdocs' version '2.3.0'
}

Python¶

Requires installed python 2.7 or 3.6 and above with pip.

Check and install python if required.

Note

Plugin will not affect global python: it will create project-specific virtualenv (in .gradle/python) and install all required (pip) modules there. This will grant build reproduction (once initialized virtualenv used for all future executions).

Tip

It is completely normal to manually remove virtualenv folder (.gradle/python) in case of problems to re-create environment.

Usage¶

By default, documentation source assumed to be in src/doc.

Tip

Default location could be changed: mkdocs.sourcesDir = 'docs'

Call mkdocsInit task to generate initial site version (into src/doc by default):

src/doc/
    docs/               - documentation source
        ...
        index.md
    mkdocs.yml          - site configuration

Note

Plugin does not use mkdocs new command for site generation: custom template used with pre-configured plugins and enabled material theme.

Call mkdocsServe task to start live reload server to see default site: http://127.0.0.1:8000/.

Tip

Used port may be changed in mkdocs.yml with dev_addr:

dev_addr: 127.0.0.1:3000

Warning

Python process will not be killed after you stop gradle execution (search and kill python process manually). This is a known gradle problem and the only known workaround is to start task without daemon: gradlew mkdocsServe --no-daemon. Another alternative is to start serve command directly: copy console command from task execution log and use it directly.

Initial site configuration¶

Open generated mkdocs config file src/doc/mkdocs.yml. It contains many commented options:

Commented option	Recommendation
site_author	fill with you name or remove (appear in meta tags only)
site_url	Set to documentation root url (gh-pages url). Used as meta tag, as a link on the home icon and inside generated sitemap.xml. NOTE plugin will automatically modify url to point to correct published folder (when multi-version publication used).
	Repository link on each page (right top corner)
repo_name	Source repository link text (by default set to project name)
repo_url	Repository url (Github or Bitbucket)
edit_uri	Path to documentation source in the source repository (required for "edit page" (pencil icon) link)
	Copyright
copyright	Shown below each page

For material theme configuration see: configuration docs.

Read about navigation configuration to fine tune navigation menus behavior (in theme.features section).

Note

Material theme supports docs version selector natively, but requires mike tool. Gradle plugin provides its own publishing implementation (not requiring mike) with exactly the same features (but easier to configure from gradle). So if you want version switcher, just enable it as shown in docs and it will work.

Another commonly used feature is dark theme toggle

Writing¶

Yaml configuration nav section declares your documentation structure. Pages inside docs folder may be structured as you want.

To add new page simply add new markdown file (page.md) and add reference to it in nav config section.

Note

All changes are immediately appeared in the started live reload server (mkdocsServe)

You can use gradle-driven variables, for example, to insert project version in docs.

Read:

Mkdocs getting started guide.
Mkdocs-material extensions. Mkdocs config generated by mkdocsInit task already enables all extensions according to recommended configuration. But you still need to know how to use them, so read this section.

Tip

If you want to use a different theme (not material) then you'll need to configure it

Building¶

Warning

You will need to stop livereload server in order to build

By default, mkdocsBuild task will generate (suppose project version is '1.0-SNAPSHOT'):

build/mkdocs/
    /1.0-SNAPSHOT/    - mkdocs site
    index.html        - redirect to correct site
    versions.json     - versions descriptor for version switcher

Plugin is configured for multi-version documentation publishing: each version is in it's own folder and special index.html at the root will redirect to the latest version (when published).

Everything in build/mkdocs/ is assumed to be published into github pages (preserving all other already published folders).

Default configuration:

mkdocs.publish {
    docPath = '$version'  
    rootRedirect = true  
}

As documentation is often updated for already released version, it makes sense to define current version manually (or define it when you need to publish to exact version):

mkdocs.publish.docPath = '1.0'

Tip

See multi-version section for how to publish older docs version

Tip

You can also use version aliases like latest or dev or 1.x and perform root redirection to alias instead of exact version (common case, show 'latest')

See examples section with most common configurations.

Single version site¶

If you don't want to use multi-version support at all then:

mkdocs.publish.docPath = ''  // or null

This way, mkdocs site will always be published at the root (in case of publish it will always replace previous site version).

Publication¶

When documentation site will be ready, you will need to call mkdocksPublish in order to publish it to github pages (default).

If your repo is https://github.com/me/my-project then documentation will be available as https://me.github.io/my-project/.

Published index.html at the root will immediately redirect you to the actual version: https://me.github.io/my-project/1.0.0/.

See more about publication customization in publication section. It also describes how to publish additional parts with documentation site (like javadoc).

Pip¶

See pip section if you need to change mkdocs version, use custom theme or plugin.