fredrikekre / fredrikekre/DocumenterCodeBlocks.jl
Too few backticks for a couple of in-line code elements in docs
- Dominant language
- Julia
- Stars
- 28
- Forks
- 1
- Avg merge
- 37m
- Merged PRs (30d)
- 2
Description
A very minor issue whose first occurrence had me stumped for a bit: In the docs, there are a few occasions where in-line code elements containing backticks are fenced by too few, leading to erroneous HTML output.
The first (and the one motivating me to file the issue at all) is:
https://github.com/fredrikekre/DocumenterCodeBlocks.jl/blob/af95de3842781c8216bccd1605a467d03b2933a1/docs/src/linenumbers.md?plain=1#L98
(that also exists in an—invisible—code comment)
https://github.com/fredrikekre/DocumenterCodeBlocks.jl/blob/af95de3842781c8216bccd1605a467d03b2933a1/src/pipeline.jl#L131
Julia's Markdown parser (unlike GFM) treats an even number of backticks as LaTeX code, and thus Documenter outputs it as $‘‘‘juliatutorial$. The fix is trivial, one just needs to add an additional backtick:
```diff
- ```` ```julia tutorial ````
+ ````` ```julia tutorial `````
```
I found two more occasions with similar issues:
https://github.com/fredrikekre/DocumenterCodeBlocks.jl/blob/af95de3842781c8216bccd1605a467d03b2933a1/docs/src/warnings.md?plain=1#L60
and
https://github.com/fredrikekre/DocumenterCodeBlocks.jl/blob/af95de3842781c8216bccd1605a467d03b2933a1/src/DocumenterCodeBlocks.jl#L66
The fixes are just as simple, triple backticks for the first example:
```diff
- `[`frob(a, b, c, d)`](@ref)`
+ ```[`frob(a, b, c, d)`](@ref)```
```
and fivefold backticks for the second:
```diff
- ` ```julia name `
+ ````` ```julia name `````
```
As "proof", I'll attach a screenshot of the Documenter output:
From my reading of the docs and a quick `grep` over the repo, I assume these are the only occurrences.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the four occurrences linked in docs/src/linenumbers.md, src/pipeline.jl, docs/src/warnings.md, and src/DocumenterCodeBlocks.jl, then use grep to confirm the issue's scan. Adjust each inline-code fence to use enough backticks for its contents, and verify that the affected documentation renders without erroneous HTML output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- julia
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100