<!--
// ┌───────────────────────────────────────────────────────────────┐
// │ Contents of README.md                                         │
// ├───────────────────────────────────────────────────────────────┘
// │
// ├──┐toc
// │  ├── What is it?
// │  ├── Why should I use it?
// │  ├── How does it work?
// │  ├── How can I install it?
// │  ├── How can I contribute?
// │  └── What has changed from previous versions?
// │
// └───────────────────────────────────────────────────────────────
-->

# toc

<p align="center">
 <b>Generate a table of contents from the comments of a file</b>
</p>

<!-- PyPi fix-->
<!--![Example table of contents generated by toc](images/showcase.webp)-->

![Example table of contents generated by toc](https://github.com/AlphaJack/toc/raw/master/images/showcase.webp)

## What is it?

`toc` is a [CLI](https://en.wikipedia.org/wiki/Command-line_interface) utility to generates [Table of Contents](https://en.wikipedia.org/wiki/Table_of_contents) of text files.
It aims to be the [`tree`](https://en.wikipedia.org/wiki/Tree_%28command%29) for the contents of a file, instead of a directory.

`toc` comes with native support for Markdown, AsciiDoc, reStructuredText, HTML and many more.
It can support any language through a special kind of comments.[^1]

## Why should I use it?

Few reasons that you may consider:

- it can make your files and code base understandable in seconds, to you and others
- you can jump directly to the section you need to edit, because you see where it's located
- it makes you reflect about the structure of your file

## How does it work?

For markup languages such as Markdown, AsciiDoc, reStructuredText and HTML, no changes are needed.
For other languages (e.g. C), write some comments representing the different sections of a file.[^1]
After this, run `toc` on that file to turn those comments into a table of contents.

Comments are structured in this way:

![Syntax of comments used to generate table of contents](https://github.com/AlphaJack/toc/raw/master/images/syntax.webp)

By running `toc file.c`, you will read the table of contents of that file:

![Toc generated from syntax comments](https://github.com/AlphaJack/toc/raw/master/images/simple.webp)

## How can I install it?

First, you need [Python](https://www.python.org/downloads/) installed in your system.

Then, you can install toc by running:

```bash
pip install tableofcontents
```

If you are using Arch or Manjaro Linux, you can install [toc](https://aur.archlinux.org/packages/toc) directly from the AUR.

You should now be able to run `toc -h` to display a list of parameter you can use.

<!--[USAGE.md](./USAGE.md)-->

See [USAGE.md](https://github.com/AlphaJack/toc/blob/master/USAGE.md) for step-by-step explanations of different features,
and a list of languages supported natively or that need special attention (e.g. CSS)

## How can I contribute?

See [CONTRIBUTING.md](https://github.com/AlphaJack/toc/blob/master/CONTRIBUTING.md)

## What has changed from previous versions?

See [CHANGELOG.md](https://github.com/AlphaJack/toc/blob/master/CHANGELOG.md)

[^1]: For examples of valid and invalid comments, see <https://regex101.com/r/ngzZXN/2>
