Refactor

[savetheclocktower]

I have called this “refactor“ because I made a bunch of changes and they have no common theme.

• ejs.render does not appear to be an async function, so we can clean up a lot of awaits in json2html.js. (If there's an async version of ejs.render and we start using it, I can add them back in.)
• With some tinkering, I was able to get Less to regenerate stylesheets whenever a change is made, though I still want to figure out how to get it to regenerate only the stylesheets so that I can see the changes after one second instead of ten.
• I've added a lot of the CSS changes you seemed to like.
• I moved the layouts in pulsar-api/layouts into layouts/api so that all the layouts can live in one directory. I was having trouble getting Eleventy to pick up on changes I made to those layout files, and this fixed that problem.
• No more generated content { and } to mark hovercard targets.
• Replaced the “blocks” layout with a flat list in at least one place, and I intend to make that change elsewhere as well.

I'm happy to keep this as a draft for a while as I continue to make changes:

• I prefer the light mode theme and you appear to prefer the dark mode theme, but my goal is to make the colors in each theme resemble those on the main web site more closely. (Done, more or less.)
• On page load, the dark mode theme flashes for a second before it restores my light-mode preference, which is annoying. (Fixed.)
• At some point, I will be overriding so much of Skeleton's defaults that it might be worth discussing removing our dependency on it, though we're not at that point yet. (Ehh, everything that's worth overriding has been overridden, and everything that's left would need its own replacement if we got rid of Skeleton. I don't plan to use any of its utility class names, but it can stay all the same.)
• Hovercard triggers should be links. It's good to offer the contextual information when someone hovers, but they should also expect to click on the trigger and be taken to the appropriate page. (They are now links, but their hrefs are # until the card loads, at which point I fill them with the correct href. The long-term solution is to figure out how to bake that href into the source code directly — which may require more than one pass in the parsing phase.) (This is now done, and it works in one pass because of various tricks and inferences we can make. (foo-bar is a package name, FooBar is a class name, and ::fooBar and Foo::bar are unambiguous references to API methods in context.))
• It would be useful to have some sort of convention for naming things in the CSS. BEM is my least favorite of these schemes… except for all the others. This is not urgent, though. (This is done.)

[savetheclocktower]

Big new feature: the platform switcher! This was my favorite feature of the old docs.

Rewrote all the references to keybindings/menu items/file locations to use spans with inline class names for each platform, just like how the Flight Manual used to do it.

[savetheclocktower]

Restyled the custom containers:

Also styled the tab containers to match:

[confused-Techie]

@savetheclocktower Thanks a ton for this! I'll see what I can do about reviewing this in the near future, but at a glance these changes are looking awesome!

[savetheclocktower]

Yeah, sorry. I started moving really quickly and this PR got unwieldy.

[confused-Techie]

One thing I'll quickly add, from looking at these changes it looks like you've converted all of [[Key]] to <kbd>Key</kbd>. I had switched those over thinking it simplified reading things and used markdown-it-kbd to handle the conversion, but if we would rather just use the actually HTML, you can probably also remove that package from the repo

[savetheclocktower]

One thing I'll quickly add, from looking at these changes it looks like you've converted all of [[Key]] to <kbd>Key</kbd>. I had switched those over thinking it simplified reading things and used markdown-it-kbd to handle the conversion, but if we would rather just use the actually HTML, you can probably also remove that package from the repo

I didn't convert them all — only in cases where the hotkey varies per platform. Otherwise I'd have to wrap [[Key]] in a tag like <span class="platform-mac"> and I didn't see the point in that. Lots of the [[Key]] usages remain.

[savetheclocktower]

Maybe it would help if I gave a summary of my changes? Let me try to list them in rough order of impact on the codebase:

1. Addition of the platform switcher. Small impact for the UI of the switcher, large impact in that I replaced all instances of platform-specific keys (the LNX:/MAC:/WIN: sections). That’s probably the biggest reason why this PR touches so many files. The platform switcher starts out by making an educated guess based on your platform, but will remember your choice in localStorage the same way it remembers your theme.
2. As I had occasion to touch the Markdown files anyway, I made some changes to phrasing and content… but mostly I undid the hard-wrapping at 80 characters. I think that’s a holdover from the Flight Manual days, but it’s such a strange choice. I could’ve spent twice as much time reformatting each change I made to keep the hard wrap, but instead I just unwrapped each paragraph I touched. (If we want to keep the hard wrap, it should be applied automatically somehow, like a version of Prettier but for Markdown. That must exist, right?)
3. I redid the sidebar metadata so that the link property didn’t just point to the article slug, but to the entire absolute path from the root. This means that the sidebar links can be used much more flexibly. I also added an indexTitle property so that the sidebar could display proper breadcrumbs rather than just use “Summary” for a page’s parent article.
4. The theme switcher. I wanted equivalent functionality to what we see on the main Pulsar site, so I borrowed the icons and the three-phase dark/light/auto behavior. It’s in auto mode by default.
5. The auto-TOC behavior is inspired by (but entirely reverse-engineered from) the similar behavior on the Pulsar site.
6. I made some changes to the layout. The sidebar is a fixed width and a permanent presence on the left side once the window is at least 1000px wide (we might be able to make room for it at a smaller breakpoint, too).
7. I restyled custom containers to resemble their equivalents on the main site as much as possible.
8. I changed our approach to “sibling” page navigation so that pages link to their next/previous siblings in the footer. This frees up more space in the sidebar for heading-based table-of-contents navigation.
9. Reworked the page header to function very similarly to that of the main site, including the underline effect on hover and the blurred background.

I’ve got some more changes in the pipeline, but I don’t plan to put them into this PR just because it’s already overloaded:

• I want to do some tweaking to the main page. That would involve adding a summary to each of the top-level sections, but that brings me to my next problem:

• I’d like to do some reorganizing of content so that we can eliminate at least one of...

  • Developing for Pulsar
  • Behind Pulsar
  • Package Guides

  …because I don’t know how to structure them or summarize each section’s content. They overlap in subject matter a bit too much.

• I imagine you’ve got thoughts about syntax highlighting, but I installed the official syntax highlighting plugin and it seems to be working fine. I gave it about half a dozen colors in each theme so that dark mode’s code blocks look like One Dark and light mode’s code blocks look like One Light. (It’s using Prism under the hood, which is pretty easy to understand… so I might even be able to write a syntax highlighter for SCM files!)

I know that I threw a lot at you, so if you’d rather see any of these changes in isolation, I’ll see if I can make it happen.

[confused-Techie]

Sorry I didn't respond earlier.

But I do agree that some of those sections are a bit strange. Since I've already restructured all of the content here, there were some pieces that didn't quite fit in the end.

But for the following here's what I'd think:

• Package Guides: I'd really hope we can keep this one, since I think it's monumentally helpful to have working examples and explanations of real code to learn things. And the package guides do exactly that. Plus that's somewhere I'd really like to expand on. As for summarizing, I'd go with something like "Example package's using common Pulsar Features"
• Developing for Pulsar: I honestly think this one is fine as is, being the most fleshed out of all the sections you called out
• Behind Pulsar: This is absolutely one that doesn't fit. Maybe we could pull that section apart putting much of it's information into "Using Pulsar" as that's where we dive into specific features, and this could work there? At least for things like Keymaps, whereas serialization and such can be moved into the developing section.

What do you think of the above?

Also now that I have some time I'm going to get on testing all the changes in this PR, so again my bad on taking a while, but it seems you've certainly found lots to improve in the meantime

[confused-Techie]

Also @savetheclocktower Just wanting to say, I've finally fired up all of these changes locally, and just wow. It looks amazing, I'm very glad you've opted to leave much of the hovercard behavior since I was a fan of that, but you are right that with the right styling the list of items does look great on overview pages, and I love that you brough over the auto-TOC from the other site, that one does really pay off.

The portability of everything is quite impressive, making sure that hovercard resolution within the API docs resolve not only to current versions but also classes, and the changes to links in the sidebar making things a bit easier to work with is all awesome. I'll poke around a bit more then look at the code and see if we can get this one merged before it becomes too unwieldy

[savetheclocktower]

Great, thanks.

As for restructuring, I've been saving that for another PR, but I'll come up with something. I don't want it to seem like something you have to read all of, but I would like for it to make sense if you wanted to read it in linear fashion.

[savetheclocktower]

The only slight annoyance is the auto-generated TOC getting cut off on some resolutions. If anything we may want to check about adding a title tag to reveal the full text on hover.

Yeah, good call. I'll add a title attribute to all generated links later on.