lint: All Markdown in track definitions should lint properly #150

coriolinus · 2020-11-26T11:02:57Z

In particular, fragments such as introdcution.md, instructions.md, and the like, should have no issues reported by markdownlint or a comparable linter. In particular, that implies these properties:

All files begin with a level-1 title
No title has a level more than 1 greater than the previous title

Why?

It's easier for file authors to ensure their files are valid if they can run a lint locally
Ensuring a consistent style makes things faster for everyone
There's already been some discussion about what makes a Markdown document valid

Why not?

We need to change the site templates, which right now inject their own titles
We need to batch-update all existing markdown files
We need to apply a (pretty trivial) transformation to the markdown files to normalize the headings when they're injected into a larger file

Even so

In my opinion, the benefits outweigh the drawbacks. We have some temporary pain while we update existing files, but from then on, it becomes easier to work with markdown to ensure that the editing experience is smooth and the rendered content is consistent.

The text was updated successfully, but these errors were encountered:

iHiD · 2021-01-28T23:03:07Z

Sorry @coriolinus. I missed this. I'll move it to a different repo (as this is closing) and reply next week.

iHiD · 2021-02-03T17:26:28Z

@coriolinus For your first rule, are you happy to change it to

Any initial title must be level-1 title

Not all documents should have a heading, but if they do, I'm ok with that heading always being a #.

coriolinus · 2021-02-03T17:39:12Z

Honestly, my goal is to stop markdownlint from complaining. There are at least two different markdownlint implementations, but they share that rule: 1 2.

It's not obvious to me which templates don't work properly with a top-level header. What would be an example?

iHiD · 2021-02-03T17:52:27Z

Yeah, so basically every file would need that top level heading removed from it before it's rendered. That already happens in lots of places in the UI, where the docs are used for content but not headings.

Take as an example:

The heading on the website is unrelated to the content in the document. In v3 this becomes more acute as things like READMEs are generated from lots of files being pieced together, with various headings conditionally inserted.

So a proposal that would work for me is that we say every document must start with # but that all # will always be removed before being rendered. I could probably get behind that, although it'll potentially mean some cleanup of existing files (but a lot of that is happening anyway with the evolution of exercises in v3)

coriolinus · 2021-02-03T17:59:25Z

So, in the rendered contact page, there is in fact a header directly above the content. I don't know if that's hardcoded right now or what, but long-term, it seems to me that just rendering that header from the markdown file wouldn't cause huge issues.

Still, I'd rather incremental improvements over all-or-nothing. Would it work for you if the policy were: every document must start with #, but that some # may be removed pre-rendering? As a practical matter, we could universally trim them at least at first, but this wording of the policy means that we can incrementally move to rendering the headers properly.

iHiD · 2021-02-03T18:58:49Z

So, in the rendered contact page, there is in fact a header directly above the content. I don't know if that's hardcoded right now or what

It's hardcoded yes. A blog is maybe another good example, where the header is separated from the content by quite a lot of "noise" (e.g. a video) in v3, so it can't be just parsed as the markdown. In that example,

it seems to me that just rendering that header from the markdown file wouldn't cause huge issues.

it probably wouldn't here, but in other places, it wouldn't work.

To be clear, I don't mind stripping the headers out at the website level. I just don't really want different rules for different files, as that gets really complex quickly at the website end. So as long as we have a "global' rule, I'm ok.

In parallel to posting here, I've also spent some time bouncing this 1-1 with a few people (easier than doing it in here where it would probably have degraded into people taking "sides").

I can get consensus for:

All docs start with a level-1 title. This is removed before it gets into the "Exercism" website/CLI/etc. So level-1 headings are there purely there for consumers on GH.
No title has a level more than 1 greater than the previous title
Use h2 - h4 for semantic headings. (I don't think we need more than 3 layers of nesting)
We add this to linting rules in conflglet etc

I think there are three categories of docs that get "used" in Exercism:

Problem Specs docs (e.g. description.md)
Website Copy docs (e.g. contact.md)
Track docs (e.g. TESTS.md)

1 can be handled by crowd-sourcing people checking the descriptions. We can put a project together for this and ask people for help. It's a relatively trivial job to do each individual one, so good low-hanging fruit for contributors.
2 is trivial - I'll do it.
3 is going to be largely addressed by the ensuing chaos of Document practice exercise files docs#36 (still WIP - comments welcome) anyway, so we can work it out as part of that.

@coriolinus If you're happy with this, I'll put together a "clean" issue and check no-one majorly objects, and then we can update the docs etc, and Erik can do his thing of script-PRing everything :)

Thanks for raising this :)

coriolinus · 2021-02-03T19:29:36Z

Ok, that works for me. Thanks!

…

On Wed, Feb 3, 2021, 20:21 Jeremy Walker ***@***.***> wrote: So, in the rendered contact page, there is in fact a header directly above the content. I don't know if that's hardcoded right now or what It's hardcoded yes. A blog is maybe another good example, where the header is separated from the content by quite a lot of "noise" (e.g. a video) in v3, so it can't be just parsed as the markdown. In that example, it seems to me that just rendering that header from the markdown file wouldn't cause huge issues. it probably wouldn't here, but in other places, it wouldn't work. To be clear, I don't mind stripping the headers out at the website level. I just don't really want different rules for different files, as that gets really complex quickly at the website end. So as long as we have a "global' rule, I'm ok. ------------------------------ In parallel to posting here, I've also spent some time bouncing this 1-1 with a few people (easier than doing it in here where it would probably have degraded into people taking "sides"). I can get consensus for: - All docs start with a level-1 title. This is removed before it gets into the "Exercism" website/CLI/etc. So level-1 headings are there purely there for consumers on GH. - No title has a level more than 1 greater than the previous title - Use h2 - h4 for semantic headings. (I don't think we need more than 3 layers of nesting) - We add this to linting rules in conflglet etc I think there are three categories of docs that get "used" in Exercism: 1. Problem Specs docs (e.g. description.md) 2. Website Copy docs (e.g. contact.md) 3. Track docs (e.g. TESTS.md) - 1 can be handled by crowd-sourcing people checking the descriptions. We can put a project together for this and ask people for help. It's a relatively trivial job to do each individual one, so good low-hanging fruit for contributors. - 2 is trivial - I'll do it. - 3 is going to be largely addressed by the ensuing chaos of exercism/docs#36 <exercism/docs#36> (still WIP - comments welcome) anyway, so we can work it out as part of that. @coriolinus <https://github.com/coriolinus> If you're happy with this, I'll put together a "clean" issue and check no-one majorly objects, and then we can update the docs etc, and Erik can do his thing of script-PRing everything :) Thanks for raising this :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB3V4TWRNBTG7ECND3DE66TS5GMHVANCNFSM4WX4PR2Q> .

This adds a markdown specification document. Please see exercism/configlet#150 (comment) for the rationale of these choices.

iHiD · 2021-02-03T21:04:41Z

Added here: exercism/docs#38 🙂

iHiD · 2021-02-03T23:33:49Z

@coriolinus, my initial work on this:

Would also appreciate your opinion on:

Add markdown one-line-per-line layout rule docs#41

See exercism/configlet#150 (comment) for the rationale of these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* Create markdown specification document This adds a markdown specification document. Please see exercism/configlet#150 (comment) for the rationale of these choices. * Update contributing/standards/markdown.md Co-authored-by: Sascha Mann <git@mail.saschamann.eu> * Link to Markdown standards in linting rules * Update contributing/standards/markdown.md Co-authored-by: Erik Schierboom <erik_schierboom@hotmail.com> Co-authored-by: Sascha Mann <git@mail.saschamann.eu> Co-authored-by: Erik Schierboom <erik_schierboom@hotmail.com>

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 (comment) for the rationale of these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* Create markdown specification document This adds a markdown specification document. Please see exercism/configlet#150 (comment) for the rationale of these choices. * Update contributing/standards/markdown.md Co-authored-by: Sascha Mann <git@mail.saschamann.eu> * Add markdown one-line-per-line layout rule * Update contributing/standards/markdown.md Co-authored-by: Erik Schierboom <erik_schierboom@hotmail.com> * Update contributing/standards/markdown.md Co-authored-by: Erik Schierboom <erik_schierboom@hotmail.com> * Add linting rules (#45) * Add linting rules * Update contributing/standards/markdown.md Co-authored-by: Erik Schierboom <erik_schierboom@hotmail.com> Co-authored-by: Erik Schierboom <erik_schierboom@hotmail.com> Co-authored-by: Sascha Mann <git@mail.saschamann.eu> Co-authored-by: Erik Schierboom <erik_schierboom@hotmail.com>

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* [v3] Add level one headings to Markdown files. All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). * [v3] Markdown sub-headings must be parent level incremented by one. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* [v3] Add level one headings to Markdown files. All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). * [v3] Markdown sub-headings must be parent level incremented by one. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* [v3] Add level one headings to Markdown files. All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). * [v3] Markdown sub-headings must be parent level incremented by one. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* [v3] Add level one headings to Markdown files. All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). * [v3] Markdown sub-headings must be parent level incremented by one. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* [v3] Add level one headings to Markdown files. All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). * [v3] Markdown sub-headings must be parent level incremented by one. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* [v3] Add level one headings to Markdown files. All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). * [v3] Markdown sub-headings must be parent level incremented by one. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

* [v3] Add level one headings to Markdown files. All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). * [v3] Markdown sub-headings must be parent level incremented by one. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

ee7 · 2021-05-09T09:29:22Z

@ErikSchierboom are we happy to close this now that we have #249 and exercism/docs/building/markdown/markdown.md?

I haven't checked that all the points raised in this issue are addressed in those places.

ErikSchierboom · 2021-05-09T11:30:42Z

Yes.

All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).

iHiD transferred this issue from exercism/v3 Jan 28, 2021

iHiD added a commit to exercism/docs that referenced this issue Feb 3, 2021

Create markdown specification document

636cbb2

This adds a markdown specification document. Please see exercism/configlet#150 (comment) for the rationale of these choices.

iHiD mentioned this issue Feb 3, 2021

Create markdown specification document exercism/docs#38

Merged

ErikSchierboom mentioned this issue Feb 4, 2021

[v3] Add level one headings to Markdown files ErikSchierboom/fsharp#130

Closed

ErikSchierboom mentioned this issue Feb 5, 2021

[v3] Update to latest spec ErikSchierboom/fsharp#131

Closed

ErikSchierboom mentioned this issue Feb 5, 2021

[v3] Update to latest spec ErikSchierboom/fsharp#132

Closed

ErikSchierboom mentioned this issue Feb 5, 2021

[v3] Update Practice Exercises to latest spec ErikSchierboom/fsharp#133

Closed

ErikSchierboom mentioned this issue Feb 5, 2021

[v3] Update Practice Exercises to latest spec ErikSchierboom/fsharp#134

Closed

ee7 changed the title ~~All Markdown in track definitions should lint properly~~ lint: All Markdown in track definitions should lint properly May 9, 2021

ee7 closed this as completed May 9, 2021

ee7 added cmd: lint kind: feature User-facing enhancement labels May 10, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

lint: All Markdown in track definitions should lint properly #150

lint: All Markdown in track definitions should lint properly #150

coriolinus commented Nov 26, 2020

iHiD commented Jan 28, 2021

iHiD commented Feb 3, 2021

coriolinus commented Feb 3, 2021

iHiD commented Feb 3, 2021

coriolinus commented Feb 3, 2021

iHiD commented Feb 3, 2021

coriolinus commented Feb 3, 2021 via email

iHiD commented Feb 3, 2021

iHiD commented Feb 3, 2021

ee7 commented May 9, 2021

ErikSchierboom commented May 9, 2021

lint: All Markdown in track definitions should lint properly #150

lint: All Markdown in track definitions should lint properly #150

Comments

coriolinus commented Nov 26, 2020

Why?

Why not?

Even so

iHiD commented Jan 28, 2021

iHiD commented Feb 3, 2021

coriolinus commented Feb 3, 2021

iHiD commented Feb 3, 2021

coriolinus commented Feb 3, 2021

iHiD commented Feb 3, 2021

coriolinus commented Feb 3, 2021 via email

iHiD commented Feb 3, 2021

iHiD commented Feb 3, 2021

ee7 commented May 9, 2021

ErikSchierboom commented May 9, 2021