Add '--ordered option' to toc generation #34
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Functionally backwards compatible. Moves the regex crate from
dev-dependencies into the main dependencies.
In many (probably most) cases, the Table of Contents generated will look
like this:
```
* [1. foo](0001-foo.md)
* [2. bar](0002-bar.md)
* [3. baz](0003-baz.md)
```
In my opinion this is ugly markdown, since it generates an unordered list and
adds unsyntactic ordering after the fact. When rendered, it will look a
lot like an ordered list, but with useless bullets in front of each
item.
This patch adds a flag to leverage the common title structure
generated by adrs to create a cleanly ordered list:
```
1. [foo](0001-foo.md)
1. [bar](0002-bar.md)
1. [baz](0003-baz.md)
```
Without the flag, output is unchanged. A few notes on error catching:
* This feature is implemented against the commonmark standard, so only
up to 9 digits are allowed in the identifier in the title. Please do
not write a billion ADRs and attempt to generate a TOC with this flag.
* While these cases will not come up if ADRs are generated with adrs,
some allowances are made for custom setups:
* Ordering is done entirely based on title contents. If the file has a
conflicting number, or none at all, it will be disregarded. This
allows for a slightly DRYer setup if desired.
* Numbers cannot be missing, as commonmark has no allowances for
out-of-order ordered lists.
* All ADR titles must start with a valid ordered list identifier. This
feature does not allow mixing and matching between styles.
|
Hi @joshrotenberg , thanks for maintaining this tool! I made a patch to fix a minor nit that I had with the output of most adr tools I've come across. Please let me know if this is a feature you're open to and/or if you have any suggestions for improvements. |
Thanks for this! I'll take a closer look later today, but I'm definitely open to this (and other) new features if you have more ideas. |
joshrotenberg
approved these changes
Apr 22, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Functionally backwards compatible. Moves the regex crate from dev-dependencies into the main dependencies.
In many (probably most) cases, the Table of Contents generated will look like this:
In my opinion this is ugly markdown, since it generates an unordered list and adds unsyntactic ordering after the fact. When rendered, it will look a lot like an ordered list, but with useless bullets in front of each item.
This patch adds a flag to leverage the common title structure generated by adrs to create a cleanly ordered list:
Without the flag, output is unchanged. A few notes on error catching: