https://docs.github.com/en/free-pro-team@latest/actions/guides/caching-dependencies-to-speed-up-workflows

Most of the time is spent waiting for npm to install dependencies. Could most likely get sub 10 second builds with caching enabled.

It would be nice to be able to write articles. The articles would be sorted chronologically and an excerpt displayed automatically on an index page.

Use case would be for writing long form articles about the development process of a project, latest features, community communication, etc.

Add the ability to document multiple versions of the a project.

Using semantic versioning as an example:

You write docs for a version 1.0.0, your application gets a lot of breaking changes and you now have version 2.0.0, how do you preserve the 1.0.0 docs. Most likely you'll still want to edit them.

More thinking is needed to find the right workflow.

It's a good practice for the main readme to do outbound links to the generated docs site. Those links are set to open a new tab with within the generated site though.

When doing a code block:

```rust
// Test
```

Would be nice to be able to do something like:

```rust : other
// Test
```

The effect would be that the highlighting would use the rust syntax but the language shown in the top right would be other.

Sometimes it's useful to add some meta information in a page. For example a note, call to action, warning, tip, etc. Each one would require some special styling.

A backward compatible way of doing this would be with a blockquote:

Note: Hello world!

> Note: Hello world!

Some examples can be seen in the vuejs documentation:

• https://vuejs.org/v2/guide/
• https://v3.vuejs.org/guide/introduction.html

Since the front page gets copied to the docs folder, the link is broken. Would be nice to write a nunjucks filter that output the right github path.

As a side note, I notice that the link is hardcoded to this repo! 😑

It could be nice to support drafts. Perhaps it could be done by adding a draft suffix to a file. hello.draft.md. A draft would not get published to the static site.

Each page that has an h1 heading should have that heading be used for the page title in the HTML.

Same as the default behavior on GitHub. Hovering a heading should show a # next to it with a link to the anchor id.

Could be useful for adding a link to the page license.

https://css-tricks.com/strategies-for-cache-busting-css/

Right now, the generated CSS always has the same name. It would be good to do a bit of work so that when the CSS changes, the cache gets busted.

Given this navigation hierarchy:

• Getting Started
• Tutorials
  • Tutorial 01
  • Tutorial 02
• API
  • API 01
  • API 02

While on the Getting Started page, the navigation should look like:

• Getting Started
• Tutorials
• API

While in the Tutorials section:

• Getting Started
• Tutorials
  • Tutorial 01
  • Tutorial 02
• API

Right now when no SVG is provided for a nav link, a circle SVG is shown. This helps preserve the alignment with other links that have an SVG set.

It would be nice to not put any SVG when all of the same level links don't have an SVG set.

Result:

It would be nice to have a page that shows release notes. Might be nice if that page is automated.

Needs some thinking to figure out the right workflow.

It would be nice to figure out a workflow for translating pages in different languages.

For a relative link to an image that isn't in the docs folder, currently the link that's generated has the full repo url prepended:

https://github.com/Apostolique/apos-docs/tree/main/Images/Showcase.gif

The correct link should be:

https://raw.githubusercontent.com/Apostolique/apos-docs/main/Images/Showcase.gif

Add a search either built-in or using an external site like https://duckduckgo.com/.

Most social sites have support for the Twitter Cards or Open Graph protocols. This gives links posted to those sites some special styling.

It's possible to check what a Twitter Card will look like with: https://cards-dev.twitter.com/validator.
It's possible to check what an Open Graph card will look like with: https://www.opengraph.xyz/.

The goal here would be to automate the generation for those tags. It should also be possible to provide a card image for any page as well as a default for the site itself.

For a site with only one page and no sidebar links or social links, sidebar could be hidden.

This is a follow up to #11.

Right now the description for each page is hard coded to the site's description. It would be better to make a unique excerpt for each page. Most likely based on the first <p> tag in that page.

The current way of handling favicons isn't ideal, it's hard-coded at img/Icon.png.

Read these for inspiration and best practices:

• https://css-tricks.com/favicon-quiz/
• https://css-tricks.com/svg-favicons-and-all-the-fun-things-we-can-do-with-them/

When pages get renamed, it's nice to be able to redirect the old page to the new page. https://superdevresources.com/redirects-jekyll-github-pages/

Provide a custom layout for page redirects.

When trying to print a page, the whole content is cropped into a single page with a scrollbar.