# Markdown Contents Generator
Generate table of contents for markdown files.
- [Installation](#installation)
- [Install via PIP](#install-via-pip)
- [Install from Source](#install-from-source)
- [Usage](#usage)
- [Generate Table of Contents](#generate-table-of-contents)
- [Insert Table of Contents into a File](#insert-table-of-contents-into-a-file)
- [Replace Contents Tags](#replace-contents-tags)
## Installation
### Install via PIP
Install via python _pip_ (python3 required):
```shell
pip install markdown-contents-generator --user
```
### Install from Source
Clone git-repository and make setup inside the project directory:
```shell
git clone https://github.com/fadich/markdown-contents-generator.git \
&& cd markdown-contents-generator
python3 setup.py install
```
## Usage
Once the package installed, it provides a console command:
```shell
md-contents-generator
```
You can call it with no arguments to view the instructions. The only required parameter is a path to the markdown file which table of contents you're going to generate.
### Generate Table of Contents
By proving `MARKDOWN_FILEPATH` positional parameter, you can generate its contents and check the console output results. For example:
```shell
md-contents-generator README.md
```
You will see something like that (for this README.md file):
```markdown
- [Usage](#usage)
- [Generate Table of Contents](#generate-table-of-contents)
- [Insert Table of Contents into a File](#insert-table-of-contents-into-a-file)
- [Replace Contents Tags](#replace-contents-tags)
- [Installation](#installation)
- [Install via PIP](#install-via-pip)
- [Install from Source](#install-from-source)
```
You can copy-paste it to the file you need or make auto-insertion to your working file (see below).
### Insert Table of Contents into a File
Command can be called with optional `--insert` flag:
```shell
md-contents-generator README.md --insert
```
This will automatically insert auto-generated contents inside the _contents tags_. So, before calling this command, add these tags to your markdown file:
```markdown
...
<contents-start />
<--- Your table of contents will be inserted right here
<contents-finish />
...
```
Result should be like this:
```markdown
...
<contents-start />
- [Usage](#usage)
- [Generate Table of Contents](#generate-table-of-contents)
- [Insert Table of Contents into a File](#insert-table-of-contents-into-a-file)
- [Replace Contents Tags](#replace-contents-tags)
- [Installation](#installation)
- [Install via PIP](#install-via-pip)
- [Install from Source](#install-from-source)
<contents-finish />
...
```
Note, that the insertion **replaces everything** inside the tags!
That's why, you can call it each time you update your markdown file to automatically update the table of contents. In common, these tags won't be rendered, and you can leave them in the source code if you prefer.
You can also add `style="display: none"` (or any other attributes) for your tags if needed. The only necessary is to keep the tags naming and put single tag on a single line (multiline tags do not supported).
#### Replace Contents Tags
If you'd like to insert table of contents but don't want to leave these contents tags, just call the command with both `--insert` and `--replace-tags` flags:
```shell
md-contents-generator README.md --insert --replace-tags
```
However, in this case, you will not be able to update you table of contents, and will have to generate and insert the table of contents each time manually.
Raw data
{
"_id": null,
"home_page": "https://github.com/fadich/markdown-contents-generator",
"name": "markdown-contents-generator",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "markdown-contents-generator,md-contents-generator,md,markdown,contents,contents-generator,generator,content,content-generator,table-of-contents,table-contents,contents-table,content-table,readme,readme-contents,readme-contents-generator,table-of-contents-readme",
"author": "Fadi A.",
"author_email": "royalfadich@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d3/ec/c0b673d29f89d8e4982e5998ad5b6149732e43bd6be13d3f66559d39b4d8/markdown_contents_generator-1.0.1.tar.gz",
"platform": null,
"description": "# Markdown Contents Generator\n\nGenerate table of contents for markdown files.\n\n- [Installation](#installation)\n - [Install via PIP](#install-via-pip)\n - [Install from Source](#install-from-source)\n- [Usage](#usage)\n - [Generate Table of Contents](#generate-table-of-contents)\n - [Insert Table of Contents into a File](#insert-table-of-contents-into-a-file)\n - [Replace Contents Tags](#replace-contents-tags)\n\n## Installation\n\n### Install via PIP\n\nInstall via python _pip_ (python3 required):\n```shell\npip install markdown-contents-generator --user\n```\n\n### Install from Source\n\nClone git-repository and make setup inside the project directory:\n```shell\ngit clone https://github.com/fadich/markdown-contents-generator.git \\\n && cd markdown-contents-generator\n\npython3 setup.py install\n```\n\n## Usage\n\nOnce the package installed, it provides a console command:\n```shell\nmd-contents-generator\n```\n\nYou can call it with no arguments to view the instructions. The only required parameter is a path to the markdown file which table of contents you're going to generate.\n\n### Generate Table of Contents\n\nBy proving `MARKDOWN_FILEPATH` positional parameter, you can generate its contents and check the console output results. For example:\n```shell\nmd-contents-generator README.md\n```\n\nYou will see something like that (for this README.md file):\n```markdown\n- [Usage](#usage)\n - [Generate Table of Contents](#generate-table-of-contents)\n - [Insert Table of Contents into a File](#insert-table-of-contents-into-a-file)\n - [Replace Contents Tags](#replace-contents-tags)\n- [Installation](#installation)\n - [Install via PIP](#install-via-pip)\n - [Install from Source](#install-from-source)\n```\n\nYou can copy-paste it to the file you need or make auto-insertion to your working file (see below).\n\n### Insert Table of Contents into a File\n\nCommand can be called with optional `--insert` flag:\n```shell\nmd-contents-generator README.md --insert\n```\n\nThis will automatically insert auto-generated contents inside the _contents tags_. So, before calling this command, add these tags to your markdown file:\n```markdown\n...\n\n<contents-start />\n <--- Your table of contents will be inserted right here\n<contents-finish />\n\n...\n```\n\nResult should be like this:\n```markdown\n...\n\n<contents-start />\n\n- [Usage](#usage)\n - [Generate Table of Contents](#generate-table-of-contents)\n - [Insert Table of Contents into a File](#insert-table-of-contents-into-a-file)\n - [Replace Contents Tags](#replace-contents-tags)\n- [Installation](#installation)\n - [Install via PIP](#install-via-pip)\n - [Install from Source](#install-from-source)\n\n<contents-finish />\n\n...\n```\n\nNote, that the insertion **replaces everything** inside the tags!\n\nThat's why, you can call it each time you update your markdown file to automatically update the table of contents. In common, these tags won't be rendered, and you can leave them in the source code if you prefer.\n\nYou can also add `style=\"display: none\"` (or any other attributes) for your tags if needed. The only necessary is to keep the tags naming and put single tag on a single line (multiline tags do not supported).\n\n#### Replace Contents Tags\n\nIf you'd like to insert table of contents but don't want to leave these contents tags, just call the command with both `--insert` and `--replace-tags` flags:\n```shell\nmd-contents-generator README.md --insert --replace-tags\n```\n\nHowever, in this case, you will not be able to update you table of contents, and will have to generate and insert the table of contents each time manually.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Generate table of contents for markdown files",
"version": "1.0.1",
"split_keywords": [
"markdown-contents-generator",
"md-contents-generator",
"md",
"markdown",
"contents",
"contents-generator",
"generator",
"content",
"content-generator",
"table-of-contents",
"table-contents",
"contents-table",
"content-table",
"readme",
"readme-contents",
"readme-contents-generator",
"table-of-contents-readme"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "b5d9d47c30de03010308f91bcb6d35ae",
"sha256": "384df825e742dad5aba53cf394e79fd337b4c15c2dfbd4e3890b7df853aed030"
},
"downloads": -1,
"filename": "markdown_contents_generator-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "b5d9d47c30de03010308f91bcb6d35ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7289,
"upload_time": "2022-12-31T12:51:01",
"upload_time_iso_8601": "2022-12-31T12:51:01.304947Z",
"url": "https://files.pythonhosted.org/packages/d3/ec/c0b673d29f89d8e4982e5998ad5b6149732e43bd6be13d3f66559d39b4d8/markdown_contents_generator-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-31 12:51:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "fadich",
"github_project": "markdown-contents-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "markdown-contents-generator"
}
JSON
