(#300) Fix anchor links in Markdown docs #303
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
|
|
|
I was unable to run the acceptance tests: I can access GitHub fine; so maybe it’s a Docker problem? I pretty much don’t use docker, so I have no idea. |
chelnak
force-pushed
the
fix_markdown_anchors
branch
from
dd66852 to
baf5336
Compare
Previously, anchors in generated Markdown were not unique. There were
two problems:
1. Each parameter in a class, type, function, etc. had its own anchor,
but the `name` of the anchor was just the normalized name of the
parameter. This meant that all parameters with the same name would
have the same anchor.
2. Classes, types, etc. had their `::`s removed, whiched opened the
(rare) possibility of having non-unique anchor names for unique
type names.
This fixes those problems by:
1. Using the full name of the parameter, e.g. `$my::class::param`, to
generate an anchor name.
2. Using a better anchor normalization routine. Each invalid
character, i.e. not `[a-zA-Z0-9_-]`, is converted to `-`. This
should always result in unique anchor names for standard Puppet
identifiers, since the only invalid characters sequences are `::`
and `$` (which only appears once at the beginning of the string).
Furthermore, `-` never appears in a valid Puppet identifier, so
those two cases are the only way for it to be generated.
danielparks
force-pushed
the
fix_markdown_anchors
branch
from
baf5336 to
b08df58
Compare
chelnak
approved these changes
Sep 26, 2022
|
This looks fine to me. Thank you for providing such a clear description/commit message. |
This was referenced Mar 10, 2023
Closed
b4ldr
added a commit
to b4ldr/puppetlabs-stdlib
that referenced
this pull request
Mar 14, 2023
Regenerate references with the following fix puppetlabs/puppet-strings#303
b4ldr
added a commit
to b4ldr/puppetlabs-stdlib
that referenced
this pull request
Mar 14, 2023
Regenerate references with the following fix puppetlabs/puppet-strings#303
b4ldr
added a commit
to b4ldr/puppetlabs-stdlib
that referenced
this pull request
Jun 22, 2023
Regenerate references with the following fix puppetlabs/puppet-strings#303
cegeka-jenkins
pushed a commit
to cegeka/puppet-stdlib
that referenced
this pull request
Feb 21, 2024
Regenerate references with the following fix puppetlabs/puppet-strings#303
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.
Previously, anchors in generated Markdown were not unique. There were two problems:
Each parameter in a class, type, function, etc. had its own anchor, but the
nameof the anchor was just the normalized name of the parameter. This meant that all parameters with the same name would have the same anchor.Classes, types, etc. had their
::s removed, whiched opened the (rare) possibility of having non-unique anchor names for unique type names.This fixes those problems by:
Using the full name of the parameter, e.g.
$my::class::param, to generate an anchor name.Using a better anchor normalization routine. Each invalid character, i.e. not
[a-zA-Z0-9_-], is converted to-. This should always result in unique anchor names for standard Puppet identifiers, since the only invalid characters sequences are::and$(which only appears once at the beginning of the string). Furthermore,-never appears in a valid Puppet identifier, so those two cases are the only way for it to be generated.