Semantic markdown headings #1087
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
- The old message exceeded an 80 char line width by 14 chars. - By explaining that the docs are generated from source code JSDoc, how to edit the docs is implied and does not need to be explained. - Removed documentation.js advertisment; it serves no functional purpose. Curious people will be more interested in the npm package name in dev deps rather than that a marketing name that has to be googled (documentation.js).
- Previously, headers were displayed using `p` and `strong` tags. This is semantically incorrect, and would cause subheadings to display larger than headings for nested sections on platforms such as Github. - “Parameters”, “Properties”, and “Examples” now render as headings with a dynamic level greater than the heading they are nested under.
|
Okay - I do somewhat object to the thing being called an 'advertisement' - referring to it as documentation.js is really the only way that I can prevent the unending confusion that results from JSDoc-the-code-comment-style and JSDoc-the-documentation-generator being both named JSDoc. |
|
The phrasing Most people updating documentation are library authors who set this tooling up themselves anyway. |
This can happen in another PR to unblock this one. See documentationjs#1087 (comment).
jaydenseric
changed the title
|
Okay - looks like the test fixtures need another update, and this should be good to go! |
For some reason I had to reinstall node_modules to get `yarn run test -u` to update them all correctly.
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.
Fixed heading semantics
pandstrongtags. This is semantically incorrect, and would cause subheadings to display larger than headings for nested sections on platforms such as Github.Cleaner markdown generation commentThe old message exceeded an 80 char line width (Prettier default & best practice) by 14 chars.The old instructions to update the docs by editing the source code were technically incomplete as a script somewhere would also have to be run. Explaining that the docs are generated from source code JSDoc should be sufficient; how to edit the docs can be implied. The main thing is that people know not to directly edit the generated markdown.Removed the documentation.js advertisement. Curious people can learn about it by inspecting the package dev deps and scripts.Partly fixes #1064.