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 must be completed before this version.
• Fix issues
  • #38

Plan for 8.1.10 #

Fixed #

• An md_toc.TocDoesNotRenderAsCoherentList exception is raised for big inputs (>= 50M characters) when using the benchmark script.
• Continue fixing issue #36
  • Go
    • https://github.com/ekalinin/github-markdown-toc.go
  • Ruby
    • https://github.com/SixArm/markdown-toc-generator
  • Shell
    • https://github.com/bkrem/make-toc.sh
    • https://github.com/Lirt/markdown-toc-bash
  • Nim
    • https://github.com/smallgram/md_toc
• Update existing redcarpet code from version v3.5.0 to version v3.6.0. See issue #28.

Added #

• Add code fence detection before writing TOC in place. Until version 8.1.9, 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.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 (<!--TOC-->) 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

Add or view comments