Reformat the Markdown

[savetheclocktower]

This one is noisy because I had to undo hard-wrapping. I also chose to apply some other stylistic tweaks that I'd like to defend below:

Soft-wrapping

I think this was a leftover from the Flight Manual days, but hard-wrapping at 80 characters is just too painful. (Also, the markdown-preview package treats hard wraps as line breaks, possibly in contravention of the Markdown spec; we should maybe fix that.) (Never mind, we made this configurable.)

Don’t title-case everything

This might seem controversial, but hear me out: we don’t need so many Random Acts of Capitalization in the docs. Headings, in particular, should be sentence-cased: capitalize the first word and any proper nouns… and that’s it. And not just for heading titles — for page titles, too.

If you’re skeptical, consider that this is how all headlines are written (at least in English-language newspapers). This is also how Wikipedia does things for both page titles and section headings.

Don’t even title-case terms of art

We have certain phrases that we use over and over that have special meaning in a Pulsar context. But instead of capitalizing them (Tree View, Settings View) let’s keep them lowercase (tree view, settings view).

There’s no particular reason to capitalize them; it doesn’t make things any clearer for the user. And, if taken to its logical end, we’d wonder if we should capitalize things like buffer or pane. Better to keep them their ordinary case.

If we’re worried readers won’t understand what it means, and we want to make it clear it’s a term of art, we could extend our hovercard system and use it to link to a glossary of terms.

That said, it is fitting to italicize a new term the first time it’s used — and maybe even to increase its font weight a bit, since italics aren’t so easy to spot when you’re skimming prose.

Consistent formatting of command names

On the other hand, I think we should give a distinctive style treatment to command names for the same reason we give keyboard shortcuts their own style. In many places in the documentation, we’re wrapping them in quotation marks (“Editor: Toggle Line Comments”).

Instead, I’d suggest that we make them bold — Editor: Toggle Line Comments. They’re calls to action, so I think it’s good to make them stand out.

(Humanized command names are an exception to the sentence-casing rule I propose above; better to match the casing style that we use for commands in Pulsar itself.)

[confused-Techie]

While not having the time to comment on the rest of your really well worded and put together PR body, I do want to quickly comment on calling extra attention to the command names. I think this is an awesome idea, and one that could arguable be extended to config entry names.

Since in our docs it would make a lot of sense to make the following easy to read and understand:

• Keybindings: Which we already do via <kbd>...</kbd>
• Command Names: Which you are suggesting bolding
• Config Entries: Which hasn't had anything suggested

I'd honestly be curious if there's any other HTML structure we could utilize to drive these home, or even something custom we could add. Or even take advantage of hovercards, for example with the commands, if we used hovercards to display additional information we could use that to link to in depth docs about using the command palette and then we can remove all the entries explaining how to use it before giving an actual command.

Likewise for settings it could be used to show the actual config entry as well as the name for it?

Idk, just giving some ideas here, I don't expect any of it in this PR as there's a lot of markdown to go over on both ends, just wanting to put it out here since you made a really great point that I think we can expand on

[savetheclocktower]

(gentle reminder)

[savetheclocktower]

OK, addressed the two suggestions that were easy to make. I think we can put slug generation on the to-do list; hopefully that logic can be customized.

[confused-Techie]

Thanks for addressing my concerns @savetheclocktower, if you wouldn't mind sharing your snippet to outline bad links that'd be rad! Otherwise I'll merge this and start working again on fixing links.

Do you have more changes in the pipeline? If so I can make sure to make my changes a PR to not make your life to difficult, otherwise I'll just commit straight to main

[savetheclocktower]

I have plenty of changes in the pipeline and my “bad links” styles will be among them — perhaps delivered conditionally so that they're only present locally. Now that this is merged I'd like to start reorganizing content, but it sounds like your changes are not as impactful. Probably still best to do them as PRs, but I can give quick reviews if needed.

[savetheclocktower]

For now, here's what I've dumped into globals.less:

a[href="TODO"] {
  color: red !important;
}

img[src="TODO"] {
  outline: 2px solid red !important;
}