glureau / gradle-mkdocs-plugin

Mkdocs documentation generation and publishing plugin

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

Summary

• Configuration: mkdocs
• Tasks:
  • mkdocsInit - generate initial site
  • mkdocsServe - livereload server (dev)
  • mkdocsBuild - build documentation
  • mkdocsPublish - publish to github pages
  • mkdocsVersionsFile - generate versions.json file for version switcher
  • type:MkdocsTask to call custom mdocs commands
• Enable plugins: git-publish, use-python

Setup

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

OR

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

Compatibility

Plugin compiled for java 8, compatible with java 11

Gradle	Version
5-7	2.4.0
4.x	1.1.0

Requires installed python 3.7 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

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

---