generate: demote level of other headings by 1 #328
Assignees
Labels
Comments
ee7
changed the title
4 tasks
ee7
added a commit
that referenced
this issue
Jul 1, 2022
Before this commit, the implementation of `configlet generate` was
noticeably incomplete - it could produce files with incorrect heading
levels.
Given a Concept Exercise with an `introduction.md.tpl` file like:
# Introduction
## Date and Time
%{concept:date-time}
`configlet generate` would write an `introduction.md` file, inserting
the introduction for the `date-time` Concept, but without demoting its
headings:
# Introduction
## Date and Time
Blah blah.
## A heading from the date-time `introduction.md` file
Blah blah.
With this commit, configlet will demote the level of an inserted heading
when appropriate:
# Introduction
## Date and Time
Blah blah.
### A heading from the date-time `introduction.md` file
Blah blah.
`configlet generate` now also writes the same when given the template
structure of:
# Introduction
%{concept:date-time}
That is, it adds a level-2 heading when the placeholder is not already
under a level-2 heading - we concluded that this looks better on the
website. The heading's contents are taken from the concept's `name` in
the track-level `config.json` file, so you may prefer to omit such
level-2 headings in the template file (unless you want the heading
contents to be different).
This commit also fixes configlet's handling of link reference
definitions. Consider this `introduction.md.tpl` file:
# Introduction
## Foo
%{concept:foo}
## Bar
%{concept:bar}
Before this commit, when more than one placeholder had a link reference
definition, `configlet generate` would produce something like:
# Introduction
## Foo
Here is a line with a link to [Foo][foo].
[foo]: http://www.example.com
## Bar
Here is another line with a link to [Bar][bar].
[bar]: http://www.example.org
That is, it would not combine link reference definitions at the bottom.
With this commit, it does so - ordering by first usage, and
deduplicating them:
# Introduction
## Foo
Here is a line with a link to [Foo][foo].
## Bar
Here is another line with a link to [Bar][bar].
[foo]: http://www.example.com
[bar]: http://www.example.org
The Markdown handling in this commit is deliberately rudimentary, and
has some limitations. We're doing it this way because there is no
pure-Nim Markdown parser and renderer that does what we want. The
plan is to use a wrapper for libcmark [1], the reference implementation
of the CommonMark Spec [2].
However, cmark is not designed foremost to be a Markdown formatter - for
example, it inlines a link destination from a matching link reference
definition. But we want to generate `introduction.md` files without that
inlining, so we need patch or workaround cmark's rendering. There's some
complexity there that's best left for another commit.
[1] https://github.com/commonmark/cmark
[2] https://spec.commonmark.org/0.30
Closes: #328
Closes: #626
Repository owner
moved this from In Progress
to Done
in Configlet roadmap
Jul 1, 2022
glennj
pushed a commit
to glennj/exercism-configlet
that referenced
this issue
Jul 8, 2022
…cism#620) Before this commit, the implementation of `configlet generate` was noticeably incomplete - it could produce files with incorrect heading levels. Given a Concept Exercise with an `introduction.md.tpl` file like: # Introduction ## Date and Time %{concept:date-time} `configlet generate` would write an `introduction.md` file, inserting the introduction for the `date-time` Concept, but without demoting its headings: # Introduction ## Date and Time Blah blah. ## A heading from the date-time `introduction.md` file Blah blah. With this commit, configlet will demote the level of an inserted heading when appropriate: # Introduction ## Date and Time Blah blah. ### A heading from the date-time `introduction.md` file Blah blah. `configlet generate` now also writes the same when given the template structure of: # Introduction %{concept:date-time} That is, it adds a level-2 heading when the placeholder is not already under a level-2 heading - we concluded that this looks better on the website. The heading's contents are taken from the concept's `name` in the track-level `config.json` file, so you may prefer to omit such level-2 headings in the template file (unless you want the heading contents to be different). This commit also fixes configlet's handling of link reference definitions. Consider this `introduction.md.tpl` file: # Introduction ## Foo %{concept:foo} ## Bar %{concept:bar} Before this commit, when more than one placeholder had a link reference definition, `configlet generate` would produce something like: # Introduction ## Foo Here is a line with a link to [Foo][foo]. [foo]: http://www.example.com ## Bar Here is another line with a link to [Bar][bar]. [bar]: http://www.example.org That is, it would not combine link reference definitions at the bottom. With this commit, it does so - ordering by first usage, and deduplicating them: # Introduction ## Foo Here is a line with a link to [Foo][foo]. ## Bar Here is another line with a link to [Bar][bar]. [foo]: http://www.example.com [bar]: http://www.example.org The Markdown handling in this commit is deliberately rudimentary, and has some limitations. We're doing it this way because there is no pure-Nim Markdown parser and renderer that does what we want. The plan is to use a wrapper for libcmark [1], the reference implementation of the CommonMark Spec [2]. However, cmark is not designed foremost to be a Markdown formatter - for example, it inlines a link destination from a matching link reference definition. But we want to generate `introduction.md` files without that inlining, so we need patch or workaround cmark's rendering. There's some complexity there that's best left for another commit. [1] https://github.com/commonmark/cmark [2] https://spec.commonmark.org/0.30 Closes: exercism#328 Closes: exercism#626
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Given an
introduction.md.tplfile with the structure:configlet generateproduced the Concept Exerciseintroduction.mdfile with the structure:It should demote` the level of an inserted heading when appropriate:
The text was updated successfully, but these errors were encountered: