Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use marky for README support #419

Open
tmeasday opened this issue Dec 31, 2015 · 1 comment
Open

Use marky for README support #419

tmeasday opened this issue Dec 31, 2015 · 1 comment

Comments

@tmeasday
Copy link
Member

tmeasday commented Dec 31, 2015

Continuation of #339

Npm has switched (published?) a package that they use to do their markdown formatting: https://github.com/npm/marky-markdown

Principal benefits:

  1. We don't need to go to GH to parse markdown
  2. Auto attaches ids and links to all headings.

The reason 2. is useful is that a lot of packages (especially ones that use TocDoc such as autoform), use fragment links in a table of contents in their readmes. This works on GH because GH adds (somehow) ids to all headers. So NPM does the same with marky.

It's slightly complex because to avoid id clashes, they use user-content-X where X is a canonicalized version of the heading's text, so we also need to write some code equivalent to https://github.com/npm/newww/blob/master/assets/scripts/deep-links.js to handle the rerouting of #X to #user-content-X. But this is possible.

Some packages that are useful when testing this stuff:

  1. A package with a fragment link: http://localhost:3000/aldeed/autoform (TOC)
  2. A package with an image: http://localhost:3000/mizzao/partitioner
  3. A package with a relative link: http://localhost:3000/iron/router (Guide link)

CSS fixes required

Marky has some slight differences in CSS output to GHFM that we need to deal with:

  1. Headers are all wrapped in a link, so appear blue.
  2. Code blocks are wrapped in two <pre> tags for some odd reason
  3. Also, it also now puts down some special permalink html inside the headings. They look like:
 <h1 class="deep-link"><a href="#...">Heading</a></h1>

What GH do is make the <a> element appear when you hover over the heading to the LHS as a "permalink" indicator (ss of what I'm talking about: https://www.dropbox.com/s/c7al9utmruf7ghn/Screenshot%202015-12-31%2013.33.24.png?dl=0).

We could optionally do this, although the headings acts as permalinks anyway, so it's NBD

@tmeasday tmeasday assigned tmeasday, domyen and zol and unassigned tmeasday and domyen Dec 31, 2015
@tmeasday
Copy link
Member Author

@zol can you review the PR above and if you think the approach is sensible, hand over to Dom for some hopefully minor CSS fixes that are required. (See description above)

@zol zol removed their assignment Feb 23, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants