Browse Source

Provide md-toc plugin for pre-commit framework

If a person uses to configure tests
for their git repos, they can now use md-toc as a plugin.

This commit:

- Adds `.pre-commit-hooks.yaml` to define the hook.
  It is a simple definition because md-toc ``
  is well-defined and provides a default entrypoint.

- Updates `README.rst` to provide end-user instructions.

I was hesitant to add a test to the Makefile.
However, it is easy to test via:

    # all markdown files
    pre-commit try-repo . md-toc --all-files

    # or a specific file
    pre-commit try-repo . md-toc --file

If all `*.md` files that have the TOC marker are up-to-date,
the output looks like:

    Update markdown table-of-contents........................................Passed

If any `*.md` files that have the TOC marker are updated by the plugin,
pre-commit fails the run and warns that it modified 1 or more files:

    Update markdown table-of-contents........................................Failed
    - hook id: md-toc
    - files were modified by this hook

Pre-commit automatically fails if any file is modified, which
forces the user to add the updated file to the commit.

💡 If you merge this, it would help users if you bump the
minor tag. Pre-commit users usually put a `rev: <tag>` in their
`.pre-commit-config.yaml`. They _can_ put a git hash or
`rev: latest`, but a tag is much more common.

If you merge this, I am happy to then submit a PR to pre-commit to
have it included in the index at
Paul Morgan 2 years ago
  1. 11
  2. 33


@ -0,0 +1,11 @@
# Define plugins (hooks) provided by this repo.
# How to test:
- id: md-toc
name: Update markdown table-of-contents
description: 'Replace TOC marker with a table of contents'
language: python
types: [markdown] # as detected by pre-commit with identify-cli
entry: md_toc
args: [-p, github]


@ -126,6 +126,39 @@ CLI Helps
$ md_toc redcarpet --help
Pre-commit hook
This repo provides a plugin for use with the `Pre-commit framework`_.
Sample ``.pre-commit-config.yaml`` within your git repo
to use the default plugin settings:
- repo:
rev: master # or a specific git tag from md-toc
- id: md-toc
Override the defaults via the ``args`` parameter, such as:
- repo:
rev: master # or a specific git tag from md-toc
- id: md-toc
args: [-p, --skip-lines, '1', redcarpet] # CLI options
.. _Pre-commit framework: