fredrikekre / fredrikekre/DocumenterCodeBlocks.jl

Too few backticks for a couple of in-line code elements in docs

Open Beginner friendly
#30 0 comments 0 reactions 0 assignees View on GitHub
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:

Image

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.