Mkdocs setup

.github/workflows/cli.yml

@@ -92,3 +92,17 @@ jobs:
         run: |
           git diff --exit-code
           git diff --cached --exit-code
+
+  publish:
+    if: startswith(github.ref, 'refs/tags/')
+    name: publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Publish Docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.MKDOCS_PUBLISH_GITHUB_TOKEN }}
+          REQUIREMENTS: mkdocs-requirements.txt

.gitignore

@@ -1,10 +1,10 @@
 *.coverprofile
 *.orig
-node_modules/
 vendor
 .idea
 internal/*/built-example
 coverage.txt
 /.local/
+/site/
 
 *.exe

Makefile

@@ -30,3 +30,15 @@ gfmrun:
 .PHONY: toc
 toc:
 	go run internal/build/build.go toc docs/v2/manual.md
+
+.PHONY: docs
+docs:
+	mkdocs build
+
+.PHONY: docs-deps
+docs-deps:
+	pip install -r mkdocs-requirements.txt
+
+.PHONY: serve-docs
+serve-docs:
+	mkdocs serve

docs/CNAME

@@ -0,0 +1 @@
+cli.urfave.org

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+../CODE_OF_CONDUCT.md

docs/CONTRIBUTING.md

@@ -98,6 +98,28 @@ line help system which may be consulted for further information, e.g.:
 go run internal/genflags/cmd/genflags/main.go --help
 ```
 
+#### docs output
+
+The documentation in the `docs` directory is automatically built via `mkdocs` into a
+static site and published when releases are pushed (see [RELEASING](./RELEASING/)). There
+is no strict requirement to build the documentation when developing locally, but the
+following `make` targets may be used if desired:
+
+```sh
+# install documentation dependencies with `pip`
+make docs-deps
+```
+
+```sh
+# build the static site in `./site`
+make docs
+```
+
+```sh
+# start an mkdocs development server
+make serve-docs
+```
+
 ### pull requests
 
 Please feel free to open a pull request to fix a bug or add a feature. The @urfave/cli

docs/index.md

@@ -0,0 +1,21 @@
+# Welcome to urfave/cli
+
+[![GoDoc](https://godoc.org/github.com/urfave/cli?status.svg)](https://pkg.go.dev/github.com/urfave/cli/v2)
+[![codebeat](https://codebeat.co/badges/0a8f30aa-f975-404b-b878-5fab3ae1cc5f)](https://codebeat.co/projects/github-com-urfave-cli)
+[![Go Report Card](https://goreportcard.com/badge/urfave/cli)](https://goreportcard.com/report/urfave/cli)
+[![codecov](https://codecov.io/gh/urfave/cli/branch/main/graph/badge.svg)](https://codecov.io/gh/urfave/cli)
+
+`urfave/cli` is a simple, fast, and fun package for building command line apps in Go. The
+goal is to enable developers to write fast and distributable command line applications in
+an expressive way.
+
+These are the guides for each major supported version:
+
+- [`v2`](./v2/)
+- [`v1`](./v1/)
+
+In addition to the version-specific guides, these other documents are available:
+
+- [CONTRIBUTING](./CONTRIBUTING/)
+- [CODE OF CONDUCT](./CODE_OF_CONDUCT/)
+- [RELEASING](./RELEASING/)

docs/migrate-v1-to-v2.md

@@ -1,6 +1,4 @@
-Migration Guide: v1 to v2
-===
-
+# Migration Guide: v1 to v2
 
 v2 has a number of breaking changes but converting is relatively
 straightforward: make the changes documented below then resolve any
@@ -11,25 +9,6 @@ If you find any issues not covered by this document, please post a
 comment on [Issue 921](https://github.com/urfave/cli/issues/921) or
 consider sending a PR to help improve this guide.
 
-<!-- toc -->
-
-  * [Flags before args](#flags-before-args)
-  * [Import string changed](#import-string-changed)
-  * [Flag aliases are done differently](#flag-aliases-are-done-differently)
-  * [EnvVar is now a list (EnvVars)](#envvar-is-now-a-list-envvars)
-  * [Actions returns errors](#actions-returns-errors)
-  * [cli.Flag changed](#cliflag-changed)
-  * [Commands are now lists of pointers](#commands-are-now-lists-of-pointers)
-  * [Lists of commands should be pointers](#lists-of-commands-should-be-pointers)
-  * [Appending Commands](#appending-commands)
-  * [GlobalString, GlobalBool and its likes are deprecated](#globalstring-globalbool-and-its-likes-are-deprecated)
-  * [BoolTFlag and BoolT are deprecated](#booltflag-and-boolt-are-deprecated)
-  * [&cli.StringSlice{""} replaced with cli.NewStringSlice("")](#clistringslice-replaced-with-clinewstringslice)
-  * [Replace deprecated functions](#replace-deprecated-functions)
-  * [Everything else](#everything-else)
-
-<!-- tocstop -->
-
 # Flags before args
 
 In v2 flags must come before args. This is more POSIX-compliant.  You

docs/v1/index.md

@@ -0,0 +1 @@
+manual.md

docs/v1/manual.md

@@ -1,35 +1,4 @@
-cli v1 manual
-===
-
-<!-- toc -->
-
-- [Getting Started](#getting-started)
-- [Examples](#examples)
-  * [Arguments](#arguments)
-  * [Flags](#flags)
-    + [Placeholder Values](#placeholder-values)
-    + [Alternate Names](#alternate-names)
-    + [Ordering](#ordering)
-    + [Values from the Environment](#values-from-the-environment)
-    + [Values from files](#values-from-files)
-    + [Values from alternate input sources (YAML, TOML, and others)](#values-from-alternate-input-sources-yaml-toml-and-others)
-    + [Precedence](#precedence)
-  * [Subcommands](#subcommands)
-  * [Subcommands categories](#subcommands-categories)
-  * [Exit code](#exit-code)
-  * [Combining short options](#combining-short-options)
-  * [Bash Completion](#bash-completion)
-    + [Enabling](#enabling)
-    + [Distribution](#distribution)
-    + [Customization](#customization)
-  * [Generated Help Text](#generated-help-text)
-    + [Customization](#customization-1)
-  * [Version Flag](#version-flag)
-    + [Customization](#customization-2)
-    + [Full API Example](#full-api-example)
-  * [Migrating to V2](#migrating-to-v2)
-
-<!-- tocstop -->
+# v1 guide
 
 ## Getting Started
 

docs/v2/index.md

@@ -0,0 +1 @@
+manual.md

docs/v2/manual.md

@@ -1,51 +1,4 @@
-cli v2 manual
-===
-
-<!-- toc -->
-
-- [Migrating From Older Releases](#migrating-from-older-releases)
-- [Getting Started](#getting-started)
-- [Examples](#examples)
-  * [Arguments](#arguments)
-  * [Flags](#flags)
-    + [Placeholder Values](#placeholder-values)
-    + [Alternate Names](#alternate-names)
-    + [Ordering](#ordering)
-    + [Values from the Environment](#values-from-the-environment)
-    + [Values from files](#values-from-files)
-    + [Values from alternate input sources (YAML, TOML, and others)](#values-from-alternate-input-sources-yaml-toml-and-others)
-    + [Required Flags](#required-flags)
-    + [Default Values for help output](#default-values-for-help-output)
-    + [Precedence](#precedence)
-  * [Subcommands](#subcommands)
-  * [Subcommands categories](#subcommands-categories)
-  * [Exit code](#exit-code)
-  * [Combining short options](#combining-short-options)
-  * [Bash Completion](#bash-completion)
-    + [Default auto-completion](#default-auto-completion)
-    + [Custom auto-completion](#custom-auto-completion)
-    + [Enabling](#enabling)
-    + [Distribution and Persistent Autocompletion](#distribution-and-persistent-autocompletion)
-    + [Customization](#customization)
-    + [ZSH Support](#zsh-support)
-    + [ZSH default auto-complete example](#zsh-default-auto-complete-example)
-    + [ZSH custom auto-complete example](#zsh-custom-auto-complete-example)
-    + [PowerShell Support](#powershell-support)
-  * [Generated Help Text](#generated-help-text)
-    + [Customization](#customization-1)
-  * [Version Flag](#version-flag)
-    + [Customization](#customization-2)
-  * [Timestamp Flag](#timestamp-flag)
-  * [Full API Example](#full-api-example)
-
-<!-- tocstop -->
-
-## Migrating From Older Releases
-
-There are a small set of breaking changes between v1 and v2.
-Converting is relatively straightforward and typically takes less than
-an hour. Specific steps are included in
-[Migration Guide: v1 to v2](../migrate-v1-to-v2.md). Also see the [pkg.go.dev docs](https://pkg.go.dev/github.com/urfave/cli/v2) for v2 API documentation.
+# v2 guide
 
 ## Getting Started
 
@@ -1714,3 +1667,11 @@ func wopAction(c *cli.Context) error {
   return nil
 }
 ```
+
+## Migrating From Older Releases
+
+There are a small set of breaking changes between v1 and v2.
+Converting is relatively straightforward and typically takes less than
+an hour. Specific steps are included in
+[Migration Guide: v1 to v2](../migrate-v1-to-v2.md). Also see the [pkg.go.dev docs](https://pkg.go.dev/github.com/urfave/cli/v2) for v2 API documentation.
+

mkdocs-requirements.txt

@@ -0,0 +1,4 @@
+mkdocs~=1.3
+mkdocs-material~=8.2
+mkdocs-git-revision-date-localized-plugin~=1.0
+pygments~=2.12

mkdocs.yml

@@ -0,0 +1,62 @@
+# NOTE: the mkdocs dependencies will need to be installed out of
+# band until this whole thing gets more automated:
+#
+#     pip install -r mkdocs-requirements.txt
+#
+
+site_name: urfave/cli
+site_url: https://cli.urfave.org/
+repo_url: https://github.com/urvafe/cli
+edit_uri: edit/main/docs/
+nav:
+  - Home: index.md
+  - v2 Manual: v2/index.md
+  - v1 Manual: v1/index.md
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-4
+        name: dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-7
+        name: light mode
+plugins:
+  - git-revision-date-localized
+  - search
+# NOTE: this is the recommended configuration from
+# https://squidfunk.github.io/mkdocs-material/setup/extensions/#recommended-configuration
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - meta
+  - md_in_html
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde