md-toc changelog #

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased version are marked with Plan for ${version} or Unreleased.

Plan for 10.0.0 #

Added #

Add HTML output for the TOC

Plan for 9.0.0 #

Added #

Fix issues
- #24: Feature Request: Automatically skip lines to first or (N) TOC
- #37: Is it possible to ignore certain headers?

Changed #

Snake case for all variables.
Fix and cleanup constants file.
Change default maximum header level to the maximum supported for each parser.

Removed #

Remove the deprecated md_toc.exceptions.CannotTreatUnicodeString exception.

Fixed #

Issue #25: Links not working when some styling is used in the header on GitHub: must be completed before this version.

Plan for 8.2.1 #

Fixed #

An md_toc.TocDoesNotRenderAsCoherentList exception is raised for big inputs (>= 50M characters) when using the benchmark script.
Update existing redcarpet code from version v3.5.0 to version v3.6.0. See issue #28: Redcarpet v3.5.1 is out.

Added #

Add code fence detection before writing TOC in place. Until version 8.2.0, given for example a file like this

```

<!--TOC_MARKER-->

```

# ONE

## TWO

# ONE

## TWO

### THREE

running

md_toc --toc-marker '<!--TOC_MARKER-->' -p github file.md

results in

```

<!--TOC_MARKER-->

- [ONE](#one)
  - [TWO](#two)
- [ONE](#one-1)
  - [TWO](#two-1)
    - [THREE](#three)

<!--TOC_MARKER-->

```

# ONE

## TWO

# ONE

## TWO

### THREE

instead of

```

<!--TOC_MARKER-->

```

# ONE

## TWO

# ONE

## TWO

### THREE

This means that if a TOC marker is detected within fenced code block it must be ignored. A similar problem happens if there are two TOC markers, one of them being inside a fenced code block:

```

<!--TOC_MARKER-->

```

<!--TOC_MARKER-->

# ONE

## TWO

# ONE

## TWO

### THREE

using the previous command results in

```

<!--TOC_MARKER-->

- [ONE](#one)
  - [TWO](#two)
- [ONE](#one-1)
  - [TWO](#two-1)
    - [THREE](#three)

<!--TOC_MARKER-->
<!--TOC_MARKER-->

```

<!--TOC_MARKER-->

# ONE

## TWO

# ONE

## TWO

### THREE

[8.2.0] -2023-08-08 #

Fixed #

Definetly closed issue #36: Consider Mentioning Existence of GitHub’s Built-In Markdown Table of Contents. Added more projects for feature comparisons.
Issue #38: Invalid Cross-device Link declared officially closed for inactivity (no recent reports).

Added #

Using the new --diff option enables md-toc to return 128 if the existing TOC in a file is different from the newly generated one, instead of a normal 0 value. Some CI systems don’t allow modifying files in-place when running pre-commit.

By returning something different than 0, the pre-commit pipeline fails so the user gets notified that the TOC needs to be changed. See issue #40: There are no diff unless we specify -p.

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

[8.1.9] -2023-02-10 #

Changed #

Moved some cmark constants to their appropriate files so as to mirror the upstream C code.

Fixed #

Added an API example in the README file to write the TOC in place.
Improve and update md-toc’s pre-commit hook documentation.
Continuing to fix issue #25.
Improved md-toc version history table: split versions to improve readability.

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

[8.1.8] -2023-01-06 #

Changed #

Improved TOC list detection: allow up to 3 leading spaces instead of 0 for first line of lists inside TOC markers () to be detected as real TOC content that needs to be replaced.
Use of a requirements-freeze.txt file with pinned dependencies for the development environment, computed from the requirements.txt and requirements-dev files.
Pinned fpyutils dependency at least to version 3.0.1.
Use of modern tools to install the package from the PKGBUILD file. See Standards based (PEP 517) vs setuptools or distutils

Removed #

Removed use of pkg_resources because they are deprecated.

Fixed #

Improvements for issue #38.
Continue fixing issue #36 and split feature table by subject.

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

[8.1.7] -2022-12-29 #

Added #

Add comparison table for the various tools similar to md-toc. This closes issue #36 although there is still room for improvement.

Fixed #

Use of list comprehensions instead of for loops to possibly improve speed.
Pinned YAPF and flake8 versions through the pre-commit update command in the Makefile.
Improved benchmark script
- Improved random string generation speed using ctypes.
- Bug fixes.
Continuing to fix issue #25.
Fixed pre-commit hooks.

Changed #

Implement use of setup.cfg and pyproject.toml. setup.py is now a dummy file.
Moved some pre-commit options to setup.cfg.
Replaced Pipenv environment with venv and pip commands.
Replaced distribution commands (setup.py sdist, setup.py bdist_wheel) with the build module.
Pinned fpyutils dependency at least to version 3.0.0.

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

[8.1.6] -2022-12-08 #

Fixed #

Until version 8.1.5, given for example a file like this
```
# ONE

## TWO

### THREE

### THREE

### THREE

## THREE

# ONE
```
running
```
md_toc github -l2 file.md
```
results in
```
- [ONE](#one)
  - [TWO](#two)
  - [THREE](#three)
- [ONE](#one-1)
```
instead of
```
- [ONE](#one)
  - [TWO](#two)
  - [THREE](#three-3)
- [ONE](#one-1)
```
Note the -l2 option.

md-toc works fine if you use the maximum header level (typically 6). Add a visible key in the returned struct of the md_toc.api.get_atx_heading function so that correct duplicate header counts can be performed. This means that in cases of non maximum header level selection (typically < 6) using the -l [{1,2,3,4,5,6}], --header-levels [{1,2,3,4,5,6}] option, all headers must be parsed even if they are not visible in the end.
Update documentation.
Change Sphinx theme.

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

[8.1.5] -2022-10-28 #

Added #

Added support for ignoring emphasis in HTML point braces (< ... >). See issue #25.
Added some benchmarks and a benchmark script. These benchmarks are not reproducible: random strings are generated each run. There are two purposes for these benchmarks:
- see how md-toc performance changes with each release
- detect bugs (runtime errors, exceptions especially) that are not addressed by the tests file

Fixed #

Fixed some docstring documentation. See issue #39.
Fixed variable typing using mypy git hook.

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

[8.1.4] -2022-06-15 #

Changed #

Readme is now in markdown instead of rst.

Fixed #

Improved readme according to issue #36: better description of md-toc features compared to similar solutions.
Improved TOC marker detection and TOC substitution in place: replace an existing TOC only if
- the TOC is a list
- or there is no content between the TOC markers

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

[8.1.3] -2022-04-20 #

Deprecated #

Deprecation of md_toc.exceptions.CannotTreatUnicodeString exception. This exception will be removed in version 9 of md-toc.

Fixed #

Memory improvements for operations on class instances.
Speed improvements for concatenation operations on strings.
Improved constants file.
Added square bracket support detection in emphasis for cmark. See issue 25

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

[8.1.2] -2022-04-03 #

Fixed #

Added code span support detection in emphasis for cmark. See issue 25
Ported missing code changes from cmark 0.29 to 0.30.

Note: GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.

Changed #

All cmark code has been split in separate Python modules: each module represents a C source file.
Documentation about markdown specification has been split in various files to improve readability.
Updated copyright headers.

[8.1.1] -2022-01-27 #

Fixed #

Fixed issue 30: added full support for CommonMark 0.30.

Note:
- GitHub Flavored Markdown is still at version 0.29. md-toc does its best to support both GFM 0.29 and cmark 0.30.
- Previously missing implementations for the markdown emphasis removal have not been added with this release.
Improved adherence to upstream cmark code.
Added missing values in constants.
Imported fixes from fpydocs.
Updated copyright headers.

[8.1.0] -2021-11-29 #

Fixed #

New line output is now handled correctly. See issue 33.
Updated copyright headers.
Imported fixes from fpydocs.
Metadata fixes in the setup.py file.

[8.0.1] -2021-08-20 #

Fixed #

Cmark-specific code is now more adherent to the original.
License references are now more accurate.
The PyPI wheel is now made reproducible.
Updated email.

Changed #

Cmark-specific code has been moved to a separate Python module: cmark.py.

Added #

New git hooks have been added in the pre-commit file.
Examples for unit tests of Cmark 0.30 have been checked with the existing examples.

[8.0.0] -2021-05-28 #

Changed #

Translated functions directly from cmark to treat emphasis.
md_toc.api.get_md_header and md_toc.api.get_atx_heading now support multiple lines.
Updated documentation.
Updated tests.
Updated package dependencies.

Added #

Newline string argument choice from the CLI.
Added these exceptions:
- md_toc.exceptions.StringCannotContainNewlines
- md_toc.exceptions.CannotTreatUnicodeString

Removed #

Removal of these functions:
- md_toc.api.get_generic_fdr_indices
- md_toc.api.get_fdr_indices
- md_toc.api.can_open_emphasis
- md_toc.api.can_close_emphasis
- md_toc.api.get_nearest_list_id

back to software/md-toc