Add further updates to website design

[ConorOkus]

This is an issue is to help us track, improve and implement further visual aspects of the website. Most of what we need is there, but it's important to get the base/template as solid as possible as it will be used by the BDK project. We are looking to make updates in the following areas.

• The title fonts seem to be randomly missing pixels, a rendering issue?
• Remove the expanding sidebar as it's difficult to tell what is part of the current article and what links out to other pages. (Discussion needed)
• Support for a blog page
• Vuepress: Add Algolia DocSearch #58
• Vuepress: Change the colour scheme #60

[thunderbiscuit]

First off that's some seriously good work @dennisreimann. I come from the bitcoindevkit side of things, and it's fair to say we're very interested in what you're building.

A few comments on my end:

1. The sidebar currently expends to show header tags from the selected articles. My main issue with this is that on long articles, your sidebar just grows really big and you can’t tell what’s a section of an article and what’s a link to a different article (the margins are not differentiating enough). It also feels like the sidebar is playing tricks on you: try for example to switch between articles and notice the sidebar jump up and down and grow and shrink to show/hide the headers of each given article you clicked on. The sidebar, for me, serves as a mental map of what is available/what I can read. I like it to be very stable across clicks.
2. Agree with @ConorOkus the font has odd "e" characters. I thought it was only on headers but it's actually throughout; once you're used to it it's not that bad, but it's a weird little quirk that distracts the eye IMO.

[dennisreimann]

Working on this in #50 now.

@thunderbiscuit I've made it so that only the h1 and h2 headline levels show up in the sidebar. Does this work for you?
Also changed the font import, which seems to have resolved the issue for @ConorOkus. Can you confirm it works for you too?

Preview here: https://deploy-preview-50--ldk-docs-preview.netlify.app/

[thunderbiscuit]

Very nice. Those are solid additions IMO!

[ConorOkus]

I wonder if we even need the H2 headings in the sidebar. One of my favourite docs are https://nextjs.org/docs

Looking at the current state of the docs these H2's consist of a lot of content and could be separate pages IMO.

Thoughts @dennisreimann @thunderbiscuit ?

[dennisreimann]

@ConorOkus That'd basically mean we don't show headings/an outline of the current doc in the sidebar. I'm fine either way and don't have a strong preference here.

[thunderbiscuit]

I mean for me, the "inside" of a page/article belong to that page more than the sidebar, so in that sense yes I prefer none. But restricting to h2 helped remove the clutter quite a bit. The issue of whether they should be their own separate articles is maybe more something for LDK to see.

But note the font/type hierarchy here:

The font weight/spacing/size differentiation is not that strong, and so I find it becomes muddy as to what is what when you have pieces of articles within the sidebar. Just my opinion.

[thunderbiscuit]

Something you see sometimes is a Table of Content at the top of long articles. This gives the eye a clear mapping for what's inside the article, without messing with the mental map for "what's on the website". Note also that once you click on a section of the article, it shows up with the header at the top, but can easily be mistaken for it's own page... Not that big of a deal, but is another reason why sections(h1,h2,h3 tags) and articles don't mesh well inside the same sidebar.

The screenshot above could easily fool you into thinking you're on the "Managing Channels" page, but in fact your in the "Managing Channels" section of the "Using LDK" page.

[dennisreimann]

@thunderbiscuit Ok, pushed an update that gets rid of the headings in the sidebar. Thanks for elaborating these concerns. I got a better understanding of what you mean and now tend to agree.

If pages grow to complex we can easily split them up or add a table of contents.

[thunderbiscuit]

I love how you can push changes and the Netlify test site updates immediately. It's so intuitive to iterate upon. Sick work by the way. Another hit on your VuePress long list of hits.

[ConorOkus]

Yeah, I guess my argument is that we should keep the structure so you can get an overall feel for what's in the article but they should actually be separate pages and not sections in the article because it makes the pages unnecessarily long. I suspect having separate pages will be better for SEO and search as well.

[thunderbiscuit]

Good point @ConorOkus. If everything is in gigantic pages it's harder to find what you want. And SEO I don't know enough about, but it feels like indeed it would be better to have specialized pages.

[sbddesign]

@dennisreimann Looking really good!

One subtle detail, not high priority. Have you tried the left-side border-line like this?

Ideally the left/right borders line up with the center of the illustration grids.

[dennisreimann]

@sbddesign We can fine tune that, it'd be the same as for the content container at the bottom …

[sbddesign]

@dennisreimann The blog is looking good. I noticed something that looks like an error. The left nav seems to switch when clicking on a blog post. I feel like the the individual blog post should have the same sidebar as the blog archive.

[dennisreimann]

@sbddesign Good catch, will update both things you mentioned with the next run of changes.

[sbddesign]

I'd suggest that we include a default image that is included in the OpenGraph metadata for each page. That way, the page shows up with a nice LDK branded picture when shared on social media.

(Optionally, each page could have its own meta image. For example, one might conceivably want the ability to add an image to the top of the blog post above the header -- but that could all come later.)

Specifically, for the immediate future, I am proposing having this PNG (or a PNG like this) included in the <head> section via og:image and twitter:image properties.

[sbddesign]

This is my mistake -- the grid backgrounds behind the images do not show up in dark mode. I have since found a simple solution for this in Figma that easily translates into SVG. When there is consensus on final color palette, I will make you sure I get this corrected artwork to you.

That is all I got right now, thanks for listening. 🙏

[thunderbiscuit]

Blog looks rad. Good stuff. @notmandatory have you seen this? I think it would be a great fit for us as well.

[ConorOkus]

Look very slick, found a little bug when the page 404's. After clicking return home The sidebar seems to overlay the page.

[dennisreimann]

Addressed all points mentioned :)

@ConorOkus I've created a separate issue for the Algolia search (#58), because we need to have the Vuepress version live to apply for it.

What is the state of the color scheme updates? Moved this to #60 so that we can merge and close this one?

[ConorOkus]

Thanks for the updates.

I'll chase the colour scheme up over slack, a few other components we need to change include the Features section on the landing page. Still need to identify what we want on there. I think a grid layout with each feature linking out to its own page in the docs could be the way to go but we discuss more in the slack.

We also need to integrate a footer.

[dennisreimann]

@ConorOkus Ok, let's merge the general update PR #50 and open/use separate issues to track the other things individually.

Added #61 and #62 to track the features section and footer,