Configuration¶
Configuration properties with default values:
mkdocs { // mkdocs sources sourcesDir = 'src/doc' // strict build (fail on build errors) strict = true // target build directory (publication root) buildDir = 'build/mkdocs' // automatically update site_url in mkdocs.yml before mkdocsBuild updateSiteUrl = true publish { // publication sub-folder (by default project version) docPath = '$version' // generate index.html' for root redirection to the last published version rootRedirect = true // publish repository uri (bu default the same as current repository) repoUri = null // publication branch branch = 'gh-pages' // publication comment comment = 'Publish $docPath documentation' // directory publication repository checkout, update and push repoDir = '.gradle/gh-pages' } }
By default:
- All documentation sources located in
src/doc
(andmkdocsInit
task generate stubs there) mkdocsBuild
task will build site intobuild/mkdocs
- Current project version is used as documentation folder (
build/mkdocs/$version
) - Github repository is assumed by default, so publication will be performed into
gh-pages
branch (where github will automatically detect it)
Note
In order to include something else into published docks (e.g. javadoc) see publication.
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).
Docs as module¶
Example of moving documentation into separate gradle module:
plugins { id 'ru.vyarus.mkdocs' version '1.1.0' apply false } version = '1.0-SNAPSHOT' project(':doc') { apply plugin: 'ru.vyarus.mkdocs' mkdocs { sourcesDir = 'src' } }
Default docs location simplified to simple src
because of no other sources in this module.
If we call :doc:mkdocsInit
it will generate documentation stubs like this:
Project structure:
/ /doc/ src/ docs/ ... index.md mkdocs.yaml build.gradle settings.gradle
For simplicity, gradle configuration for doc
module is declared in the main file,
but it could be declared inside doc's own build.gradle.