| Name | mark-toc JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | None |
| Summary | Generate table of contents in Markdown files based on headings |
| upload_time | 2024-10-25 06:39:38 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2017-2024 Jim Knoble Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
cli
development
markdown
pre-commit
table of contents
text
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mark-toc
[](https://editorconfig.org/)
[](https://github.com/pre-commit/pre-commit)
[](https://www.python.org)
[](https://github.com/psf/black)
[](#pre-commit-hook)
A Python tool which creates a Table of Contents for a Markdown document using
the headings in the document as in-document hypertext link references.
[begintoc]: #
## Contents
- [Installing](#installing)
- [How to Use](#how-to-use)
- [How Does It Work?](#how-does-it-work)
- [How Does It Really Work?](#how-does-it-really-work)
- [Example](#example)
- [Generating the Table of Contents](#generating-the-table-of-contents)
- [Heading Levels](#heading-levels)
- [More Options](#more-options)
- [Pre-Commit Hook](#pre-commit-hook)
[endtoc]: # (Generated by markdown-toc pre-commit hook)
## Installing
It is recommended to install **mark-toc** either:
- In its own virtual environment (for example, using [uv][]), or
- As a [pre-commit hook](#pre-commit-hook)
Once you have [uv installed][uv-install], you can use it to install `mark-toc` as follows:
uv tool install mark-toc
## How to Use
For a summary of all the available options:
uv tool run mark-toc --help
Or, with the `uvx` shortcut:
uvx mark-toc --help
Or, if you prefer to call the script directly:
/path/to/mark-toc --help
> [!TIP]
>
> There are a number of different ways to run tools that are delivered as
> Python modules. For the remainder of this document, we will use
> `uvx mark-toc` to mean whichever one you prefer for your Python
> installation and operating environment.
## How Does It Work?
**mark-toc** uses jiggerypokery to interpret and create "pseudo-comments" in the
document text which are not rendered in most flavors of
[Markdown][CommonMark], including [GitHub-flavored Markdown][].
> [!IMPORTANT]
>
> **mark-toc** only handles the "atx"-style headings beginning with `#`, not the "setext"-style
> using "underlines" with `=` or `-`.
To insert a table of contents in your document, add the following text, at the
beginning of an otherwise blank line and surrounded by blank lines, in the
spot where you want the table of contents to appear:
```
[toc]: #
```
This is the "table of contents token". For example:
```markdown
# README
This is the README.
[toc]: #
## More Info
...
```
Alternatively, you can use a "begin table of contents token" with a matching
"end table of contents token":
```
[begintoc]: #
...
[endtoc]: #
```
Anything between the "begin" and "end" tokens will be replaced with the
generated table of contents.
### How Does It Really Work?
The "table of contents token" and begin/end tokens use the [link reference
definitions][] feature of Markdown to insert a link definition that is not
intended to be referred to anywhere in the document.
As the CommonMark Spec notes:
> A link reference definition does not correspond to a structural element of a
> document. Instead, it defines a label which can be used in reference links
> and reference-style images elsewhere in the document.
A link consisting of only `#` is a valid HTML hyperlink target; it refers to
an empty fragment in the current document.
### Example
This [README][] contains begin/end tokens and serves as an example. You may
need to view the "raw" source to see them.
## Generating the Table of Contents
Once the token is in your Markdown file, run this script to generate a new
document which includes a table of contents in place of the token. For
example:
uvx mark-toc INPUTFILE.md
The result is printed to the standard output.
You can rerun this tool using a resulting document as the input, and the
existing table of contents will be replaced by a new one in the output.
### Heading Levels
By default, **mark-toc** includes all headings (except for the one
starting the table of contents itself) in the resulting table of contents, and
it prints the **Contents** heading as a top-level heading:
```markdown
# Contents
```
However, it is not uncommon for Markdown documents on GitHub (like this
[README][], for example) to use a "top-level" heading as the title of the
document, and only second-level headings or greater throughout the rest of the
document.
You can control what level the **Contents** heading appears at using the
`--heading-level` option:
uvx mark-toc --heading-level 2 INPUTFILE.md
This results in:
```markdown
## Contents
```
You can also control the "lowest" level of headings included in the table of
contents using `--skip-level`. For example, to skip top-level headings, usE;
uvx mark-toc --skip-level 1 INPUTFILE.md
This will omit all headings that start with a sinle `#` character from the
table of contents.
Combined, this looks lik:
uvx mark-toc --heading-level 2 --skip-level 1
or:
uvx mark-toc -H 2 -S 1
### More Options
**mark-toc** has more options. There's built-in help:
uvx mark-toc --help
## Pre-Commit Hook
**mark-toc** has built-in support for use with [pre-commit][] as a
pre-commit hook. Simply add the following `repo` and `hook` to the `repos`
stanza in your `.pre-commit-config.yaml`:
```yaml
- repo: https://github.com/jmknoble/mark-toc
rev: v0.4.0
hooks:
- id: mark-toc
```
This uses the `--pre-commit` option to modify Markdown files in place and emit a
message when a file is changed.
You can add arguments to the hook using the `args` keyword; for example:
```yaml
- repo: https://github.com/jmknoble/mark-toc
rev: v0.4.0
hooks:
- id: mark-toc
args: ['--heading-level', '2', '--skip-level', '1']
```
[CommonMark]: https://commonmark.org/
[CommonMark Spec]: https://spec.commonmark.org/
[GitHub-flavored Markdown]: https://github.github.com/gfm/
[link reference definitions]: https://spec.commonmark.org/0.29/#link-reference-definitions
[pre-commit]: https://pre-commit.com/
[uv]: https://github.com/astral-sh/uv
[uv-install]: https://docs.astral.sh/uv/getting-started/installation
[README]: README.md
Raw data
{
"_id": null,
"home_page": null,
"name": "mark-toc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cli, development, markdown, pre-commit, table of contents, text",
"author": null,
"author_email": "jmknoble <jmknoble@pobox.com>",
"download_url": "https://files.pythonhosted.org/packages/ae/b9/f8ae83ec729493790d4f1eaa43f9e6d2f70af4f7ecb005bc9e7e8c34752c/mark_toc-0.4.0.tar.gz",
"platform": null,
"description": "# mark-toc\n\n[](https://editorconfig.org/)\n[](https://github.com/pre-commit/pre-commit)\n[](https://www.python.org)\n[](https://github.com/psf/black)\n[](#pre-commit-hook)\n\n\nA Python tool which creates a Table of Contents for a Markdown document using\nthe headings in the document as in-document hypertext link references.\n\n[begintoc]: #\n\n## Contents\n\n- [Installing](#installing)\n- [How to Use](#how-to-use)\n- [How Does It Work?](#how-does-it-work)\n - [How Does It Really Work?](#how-does-it-really-work)\n - [Example](#example)\n- [Generating the Table of Contents](#generating-the-table-of-contents)\n - [Heading Levels](#heading-levels)\n - [More Options](#more-options)\n- [Pre-Commit Hook](#pre-commit-hook)\n\n[endtoc]: # (Generated by markdown-toc pre-commit hook)\n\n\n## Installing\n\nIt is recommended to install **mark-toc** either:\n\n- In its own virtual environment (for example, using [uv][]), or\n- As a [pre-commit hook](#pre-commit-hook)\n\nOnce you have [uv installed][uv-install], you can use it to install `mark-toc` as follows:\n\n uv tool install mark-toc\n\n\n## How to Use\n\nFor a summary of all the available options:\n\n uv tool run mark-toc --help\n\nOr, with the `uvx` shortcut:\n\n uvx mark-toc --help\n\nOr, if you prefer to call the script directly:\n\n /path/to/mark-toc --help\n\n> [!TIP]\n>\n> There are a number of different ways to run tools that are delivered as\n> Python modules. For the remainder of this document, we will use\n> `uvx mark-toc` to mean whichever one you prefer for your Python\n> installation and operating environment.\n\n\n## How Does It Work?\n\n**mark-toc** uses jiggerypokery to interpret and create \"pseudo-comments\" in the\ndocument text which are not rendered in most flavors of\n[Markdown][CommonMark], including [GitHub-flavored Markdown][].\n\n> [!IMPORTANT]\n>\n> **mark-toc** only handles the \"atx\"-style headings beginning with `#`, not the \"setext\"-style\n> using \"underlines\" with `=` or `-`.\n\nTo insert a table of contents in your document, add the following text, at the\nbeginning of an otherwise blank line and surrounded by blank lines, in the\nspot where you want the table of contents to appear:\n\n```\n[toc]: #\n```\n\nThis is the \"table of contents token\". For example:\n\n```markdown\n# README\n\nThis is the README.\n\n[toc]: #\n\n## More Info\n\n...\n```\n\nAlternatively, you can use a \"begin table of contents token\" with a matching\n\"end table of contents token\":\n\n```\n[begintoc]: #\n...\n[endtoc]: #\n```\n\nAnything between the \"begin\" and \"end\" tokens will be replaced with the\ngenerated table of contents.\n\n\n### How Does It Really Work?\n\nThe \"table of contents token\" and begin/end tokens use the [link reference\ndefinitions][] feature of Markdown to insert a link definition that is not\nintended to be referred to anywhere in the document.\n\nAs the CommonMark Spec notes:\n\n> A link reference definition does not correspond to a structural element of a\n> document. Instead, it defines a label which can be used in reference links\n> and reference-style images elsewhere in the document.\n\nA link consisting of only `#` is a valid HTML hyperlink target; it refers to\nan empty fragment in the current document.\n\n\n### Example\n\nThis [README][] contains begin/end tokens and serves as an example. You may\nneed to view the \"raw\" source to see them.\n\n\n## Generating the Table of Contents\n\nOnce the token is in your Markdown file, run this script to generate a new\ndocument which includes a table of contents in place of the token. For\nexample:\n\n uvx mark-toc INPUTFILE.md\n\nThe result is printed to the standard output.\n\nYou can rerun this tool using a resulting document as the input, and the\nexisting table of contents will be replaced by a new one in the output.\n\n\n### Heading Levels\n\nBy default, **mark-toc** includes all headings (except for the one\nstarting the table of contents itself) in the resulting table of contents, and\nit prints the **Contents** heading as a top-level heading:\n\n```markdown\n# Contents\n```\n\nHowever, it is not uncommon for Markdown documents on GitHub (like this\n[README][], for example) to use a \"top-level\" heading as the title of the\ndocument, and only second-level headings or greater throughout the rest of the\ndocument.\n\nYou can control what level the **Contents** heading appears at using the\n`--heading-level` option:\n\n uvx mark-toc --heading-level 2 INPUTFILE.md\n\nThis results in:\n\n```markdown\n## Contents\n```\n\nYou can also control the \"lowest\" level of headings included in the table of\ncontents using `--skip-level`. For example, to skip top-level headings, usE;\n\n uvx mark-toc --skip-level 1 INPUTFILE.md\n\nThis will omit all headings that start with a sinle `#` character from the\ntable of contents.\n\nCombined, this looks lik:\n\n uvx mark-toc --heading-level 2 --skip-level 1\n\nor:\n\n uvx mark-toc -H 2 -S 1\n\n\n### More Options\n\n**mark-toc** has more options. There's built-in help:\n\n uvx mark-toc --help\n\n\n## Pre-Commit Hook\n\n**mark-toc** has built-in support for use with [pre-commit][] as a\npre-commit hook. Simply add the following `repo` and `hook` to the `repos`\nstanza in your `.pre-commit-config.yaml`:\n\n```yaml\n - repo: https://github.com/jmknoble/mark-toc\n rev: v0.4.0\n hooks:\n - id: mark-toc\n```\n\nThis uses the `--pre-commit` option to modify Markdown files in place and emit a\nmessage when a file is changed.\n\nYou can add arguments to the hook using the `args` keyword; for example:\n\n```yaml\n - repo: https://github.com/jmknoble/mark-toc\n rev: v0.4.0\n hooks:\n - id: mark-toc\n args: ['--heading-level', '2', '--skip-level', '1']\n```\n\n\n [CommonMark]: https://commonmark.org/\n [CommonMark Spec]: https://spec.commonmark.org/\n [GitHub-flavored Markdown]: https://github.github.com/gfm/\n [link reference definitions]: https://spec.commonmark.org/0.29/#link-reference-definitions\n [pre-commit]: https://pre-commit.com/\n [uv]: https://github.com/astral-sh/uv\n [uv-install]: https://docs.astral.sh/uv/getting-started/installation\n [README]: README.md\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2017-2024 Jim Knoble Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Generate table of contents in Markdown files based on headings",
"version": "0.4.0",
"project_urls": {
"Repository": "https://github.com/jmknoble/mark-toc"
},
"split_keywords": [
"cli",
" development",
" markdown",
" pre-commit",
" table of contents",
" text"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a91a5e8ad69d53993ea55584d49accf2236c17788abb5b860da16e1deed06c13",
"md5": "b964fd92ba58b9b1cecd56ca25238845",
"sha256": "216bfa198df065cf77201d69a72c25dee998ec59e8d66c3bf34f41da6a3d0146"
},
"downloads": -1,
"filename": "mark_toc-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b964fd92ba58b9b1cecd56ca25238845",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 17284,
"upload_time": "2024-10-25T06:39:37",
"upload_time_iso_8601": "2024-10-25T06:39:37.100660Z",
"url": "https://files.pythonhosted.org/packages/a9/1a/5e8ad69d53993ea55584d49accf2236c17788abb5b860da16e1deed06c13/mark_toc-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aeb9f8ae83ec729493790d4f1eaa43f9e6d2f70af4f7ecb005bc9e7e8c34752c",
"md5": "4ff51b5356a113923e48b140a08b640f",
"sha256": "a8683ef4fb543be4cab4a249a4357c13b71db3f835452fcbe16004e9f8d15a73"
},
"downloads": -1,
"filename": "mark_toc-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "4ff51b5356a113923e48b140a08b640f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 34977,
"upload_time": "2024-10-25T06:39:38",
"upload_time_iso_8601": "2024-10-25T06:39:38.461360Z",
"url": "https://files.pythonhosted.org/packages/ae/b9/f8ae83ec729493790d4f1eaa43f9e6d2f70af4f7ecb005bc9e7e8c34752c/mark_toc-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 06:39:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jmknoble",
"github_project": "mark-toc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mark-toc"
}
