Gradle Mkdocs plugin
DOCUMENTATION https://xvik.github.io/gradle-mkdocs-plugin/
About
Generates project documentation with Mkdocs python tool.
Ideal for open source projects:
- Easy start: initial docs source generation
- Markdown syntax (with handy extensions)
- Great look from material theme (used by default) with extra features:
- Mobile friendly
- Embedded search
- Syntax highlighting
- Dark theme switcher
- Easy documentation contribution (jump to source)
- Multi-version documentation publishing to github pages
- Support version aliases (latest, dev, etc)
- Support mkdocs-material version switcher without mike tool usage
- Variables support
- Could work with direct python or docker.
- Could use requirements.txt file
Summary
- Configuration:
mkdocs
- Tasks:
mkdocsInit
- generate initial sitemkdocsServe
- livereload server (dev)mkdocsBuild
- build documentationmkdocsPublish
- publish to github pagesmkdocsVersionsFile
- generate versions.json file for version switchertype:MkdocsTask
to call custom mdocs commands
- Enable plugins: git-publish, use-python
NOTE: plugin is based on use-python plugin see python-specific tasks there.
Setup
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'ru.vyarus:gradle-mkdocs-plugin:3.0.0'
}
}
apply plugin: 'ru.vyarus.mkdocs'
OR
plugins {
id 'ru.vyarus.mkdocs' version '3.0.0'
}
Lightweight setup
There is also a lightweight plugin version without publication task and git-publish plugin enabling:
plugins {
id 'ru.vyarus.mkdocs-build' version '3.0.0'
}
Lightweight plugin is suitable if you don't need git publication and don't want extra tasks to appear.
Compatibility
Plugin compiled for java 8, compatible with java 11.
Gradle | Version |
---|---|
5.3-8 | 3.0.0 |
5-5.2 | 2.3.0 |
4.x | 1.1.0 |
Requires installed python 3.8 and above with pip.
Check and install python if required.
Snapshots
Snapshots may be used through JitPack
- Go to JitPack project page
- Select
Commits
section and clickGet it
on commit you want to use or usemaster-SNAPSHOT
to use the most recent snapshot
For gradle before 6.0 use buildscript
block with required commit hash as version:
buildscript {
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
classpath 'ru.vyarus:gradle-mkdocs-plugin:2450c7e881'
}
}
apply plugin: 'ru.vyarus.mkdocs'
For gradle 6.0 and above:
-
Add to
settings.gradle
(top most!) with required commit hash as version:pluginManagement { resolutionStrategy { eachPlugin { if (requested.id.namespace == 'ru.vyarus.mkdocs') { useModule('ru.vyarus:gradle-mkdocs-plugin:2450c7e881') } } } repositories { maven { url 'https://jitpack.io' } gradlePluginPortal() } }
-
Use plugin without declaring version:
plugins { id 'ru.vyarus.mkdocs' }
Usage
Read documentation
Might also like
- quality-plugin - java and groovy source quality checks
- animalsniffer-plugin - java compatibility checks
- pom-plugin - improves pom generation
- java-lib-plugin - avoid boilerplate for java or groovy library project
- github-info-plugin - pre-configure common plugins with github related info
- yaml-updater - yaml configuration update tool, preserving comments and whitespaces