RichardLitt/standard-readme

Suggestion: deep spec links

wooorm opened this issue · 3 comments

wooorm commented

Maybe it makes sense to create links for subsections, or even all the points in the spec; something like what d3 does maybe?

Also useful for a linter to link back to the spec.

For example:

# Specification

A compliant README must satisfy all the requirements listed below.

<a name="spec-requirements" href="#spec-requirements">#</a> **Requirements:**
  - <a name="file-name" href="#file-name">#</a> Be called README.md (with capitalization).
  - <a name="file-name-i18n" href="#file-name-i18n">#</a> If the project supports i18n, the file must be named accordingly: `README.de.md`, where `de` is the BCP 47 Language tag. For naming, prioritize non-regional subtags for languages.
  - ...

Yields (I don’t think it works in issues though, but it does in readme’s on GitHub):

Specification

A compliant README must satisfy all the requirements listed below.

# Requirements:

  • # Be called README.md (with capitalization).
  • # If the project supports i18n, the file must be named accordingly: README.de.md, where de is the BCP 47 Language tag. For naming, prioritize non-regional subtags for languages.
  • ...
RichardLitt commented

This sounds good to me. Got any ideas for how to do this fast?

wooorm commented

No idea for “fast”.

A simple alternative, also useful for text-based non-github browsing, is to just use headings per point.

But otherwise, a PR with some of these, and then going back and forth?!

  • 👍1
wooorm commented

I don’t think this is as important anymore. But I think PRs are welcome if someone wants to work on it!

  • 👍1