

Getting started¶

Installation¶

Releases are published to bintray jcenter, maven central and gradle plugins portal.

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

OR

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

Python¶

Requires installed python 2.7 or 3.4 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).

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. Note that most useful material theme extensions are already enabled (see markdown_extensions section).

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)

Read:

Mkdocs getting started guide.
Mkdocs-material extensions docs.

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

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

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.