/gradle-mkdocs-plugin

Mkdocs documentation generation and publishing plugin

Primary LanguageGroovyMIT LicenseMIT

Gradle Mkdocs plugin

License CI Appveyor build status codecov

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

Maven Central Gradle Plugin Portal

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

gradle plugin generator