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
• Compatible with gradle configuration cache

Summary

• mkdocs-build plugin:

  • Configuration: mkdocs
  • Tasks:
    • mkdocsInit - generate initial site
    • mkdocsServe - livereload server (dev)
    • mkdocsBuild - build documentation
    • type:MkdocsTask to call custom mkdocs commands

• mkdocs plugin adds:

  • Configuration: gitPublish
  • Tasks:
    • gitPublishReset - checkout repository
    • mkdocsVersionsFile - generate versions.json file for version switcher
    • gitPublishCopy - copy (and add) files into repository
    • gitPublishCommit - commit updates into repository
    • gitPublishPush - push commit
    • mkdocsPublish - publish to github pages (main task)

• Enable plugins: 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:4.0.1'
    }
}
apply plugin: 'ru.vyarus.mkdocs'

OR

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

Lightweight setup

There is also a lightweight plugin version without publication tasks:

plugins {
    id 'ru.vyarus.mkdocs-build' version '4.0.1'
}

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
7.0	4.0.1
5.3	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 click Get it on commit you want to use or use master-SNAPSHOT to use the most recent snapshot

• Add to settings.gradle (top most!) (exact commit hash might be used as version):

  pluginManagement {
      resolutionStrategy {
          eachPlugin {
              if (requested.id.id == 'ru.vyarus.mkdocs') {
                  useModule('ru.vyarus:gradle-mkdocs-plugin:master-SNAPSHOT')
              }
          }
      }
      repositories {                        
          gradlePluginPortal()
          maven { url 'https://jitpack.io' }                    
      }
  }    

• 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

---