5

Can somebody explain why headers in README.md, displayed correctly in github, are not rendered in npm (they are displayed like "#title")?

example: https://github.com/Cerealkillerway/versionUpdater (ok)

https://www.npmjs.com/package/version-updater (headers wrong)

Cereal Killer
  • 3,387
  • 10
  • 48
  • 80

1 Answers1

4

npm uses markdown-it, which seems to require a space between hashes and text:

#This doesn't work
# This does

I would argue that this is good style, and should be used even if the first version does work. It's much more readable in plain text, which is a big part of Markdown's goal:

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

Community
  • 1
  • 1
ChrisGPT was on strike
  • 127,765
  • 105
  • 273
  • 257
  • This is not entirely the correct answer. NPM will not show header size tags correctly to the h# – dman Jun 05 '16 at 06:35
  • 1
    @dman, I don't understand your comment. What does "NPM will not show header size tags correctly to the h#" mean? – ChrisGPT was on strike Jun 06 '16 at 03:37
  • In my github markdown H6 has a grey color and smaller in size than H3. In NPM markdown-it, H6 is the same size as H3. `### Usage \n ###### Using a single callback function` have the same Header size and color. – dman Jun 06 '16 at 03:57
  • @dman, this has nothing to do with the OP's question; Markdown is about _content_, not styling. Does NPM use an `
    ` tag for that content? If not you should contact them and ask why. They might only permit a few heading levels for some reason. If you're getting an `
    ` that you believe should be styled differently you might want to ask them about their stylesheet. As an aside, many developers [would discourage nesting an `
    ` directly inside an `

    `](http://stackoverflow.com/a/8778858/354577) since it provides poor accessibility. Consider fixing the rank of your headers.

     – ChrisGPT was on strike Jun 06 '16 at 13:05
  • No, you are wrong. The title is 'Markdown headers not displayed correctly in npm'. From your posted link, according to markdown-it: ` # This is an H1 ## This is an H2 ###### This is an H6 ` Also, I am not nesting the headers. The `\n` is there manually only to try to show there is a new line in the stackoverflow highlighting in a comment. Consider retracting your comment as it is in correct, unwarranted, and detracts from the issue. – dman Jun 06 '16 at 13:37
  • @dman, the _title_ of this question might match your problem, but the body does not. The OP specifically asks about headings 'displayed like "#title"' and links to a package that used to display the problematic behaviour. The OP's headings weren't being recognized as headings at all. Your question appears to either be about styling or about heading rank not being preserved on conversion to HTML. I'm glad to hear that you are not putting `
    ` tags directly beneath `

    ` tags, but I maintain my position.

     – ChrisGPT was on strike Jun 06 '16 at 14:11