Closed savetheclocktower closed 4 months ago
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 span
s with inline class names for each platform, just like how the Flight Manual used to do it.
Restyled the custom containers:
Also styled the tab containers to match:
@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!
Yeah, sorry. I started moving really quickly and this PR got unwieldy.
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
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 usedmarkdown-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.
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:
localStorage
the same way it remembers your theme.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.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...
…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.
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:
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
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
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.
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.
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 ofawaits
injson2html.js
. (If there's an async version ofejs.render
and we start using it, I can add them back in.)pulsar-api/layouts
intolayouts/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.{
and}
to mark hovercard targets.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(This is now done, and it works in one pass because of various tricks and inferences we can make. (href
s are#
until the card loads, at which point I fill them with the correcthref
. The long-term solution is to figure out how to bake thathref
into the source code directly — which may require more than one pass in the parsing phase.)foo-bar
is a package name,FooBar
is a class name, and::fooBar
andFoo::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.)