product-os / docusaurus-builder Goto Github PK

View Code? Open in Web Editor NEW

4.0 4.0 1.0 2.02 MB

An opinionated docusaurus theme building websites at scale.

JavaScript 62.77% Shell 18.88% CSS 16.46% Dockerfile 1.33% HCL 0.56%

docusaurus-builder's People

Contributors

Stargazers

Watchers

Forkers

vipulgupta2048

docusaurus-builder's Issues

"Changelog" and "Edit on GitHub" links are for the repo, not the docs

I noticed the "Changelog" and "Edit on GitHub" links in the top navigation bar take you to the repository from which the docs site was created. This is probably fine for a dedicated docs repo like fin-userManual-doc, where:

the Changelog mostly consists of things related to the docs, and
the user can (and should) be guided to making edits to the docs in the project README.

But imagine you're on this page https://os-docs.balena.io/faqs

Now those links take you to a changelog for meta-balena and to the meta-balena GitHub repo respectively, which would be bewildering for most.

Potentially it's useful to link to these things, but in those cases it probably makes sense to do so within the docs, not in the navigation bar where context can't be explained. So instead, maybe we:

only provide those links if the repo is dedicated, and in that case enforce what I believe should be standard anyway, and use the README as a description of the repo (eg. this is a docusaurus repo, source files are in here, output is there, references are here).
if the repo is not dedicated, remove the links and let the doc author create add details in the docs themselves if they wish. Losing a changelog link is probably no big deal for the user, and we probably want to be conscious on a per repo basis about providing a good experience for "edit on github". I know when I first joined balena, we had similar links on some of our resources and clicking them sent me into a rabbit hole of creating a useful edit and then realising I was way down the bottom of a long learning curve to figure out how to make it a useful PR.
make the links opt-in, so by default we eliminate this issue

Ideally, "Edit on GitHub" would take you to the edit page of the current file, but still that might be best to be optional for cases like meta-balena where making an edit is not for the faint-hearted.

Proposal: Infer Docs Title from README

What if someone wants their own docs title different than repo name.

Can we infer the docs title from a hidden property in the README frontmatter
Can the docs title be the first h1 heading of the README

The only thing is we need to find a solution without adding a config file.

Context: https://balena.zulipchat.com/#narrow/stream/348930-product-os.2Fflowzone/topic/more.20website.20inputs.20vs.20separate.20config.20file/near/314434126

Add product website link if available?

Product landing pages as a navbar link would help us get feature parity with the current website. Atm we neither have what those subdomains will turn out to be and probably will be a special case to implement for only products that have websites/landing pages to show.

Something to discuss for sure.

Bump Docusaurus Version

Docusaurus version 2.3.0 is released with fixes for mermaid diagrams - https://github.com/facebook/docusaurus/releases/tag/v2.3.0

Build local Website for Development & Testing of new features

Figure out a way to create a website that is built using repo's files & configuration but using the branch's updated action to make use of that website as

Local testing of new features being added to theme
Testing of all existing features supported in theme
It would be generally nice to have a website.

Find a way to use the same branch to build the new website so as to new features.

Proposal: Add Changelog in generated docs

Originally the idea was to have Changelogs be part of docs: https://6072976c.balena-fin.pages.dev/changelog
This was removed in #23

Why?

Changelogs didn't have closing tags for several elements leading to docusaurus unhappy
Changelogs had markdown links breaking leading to errors on build

With the immutable nature of Changelogs, it's very hard to change existing Changelogs to follow the latest template that have since rectified some of these issues. We can talk more about how to bring these back in a way where it's less breaking changes on build time.

Zulip: https://balena.zulipchat.com/#narrow/stream/345882-_help/topic/Where.20are.20changelogs.20created.3F

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

Lock file maintenance

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

Update Node.js to v20

Detected dependencies

dockerfile

Dockerfile

node 18-buster-slim

github-actions

.github/workflows/flowzone.yml

product-os/flowzone master

npm

package.json

@cmfcmf/docusaurus-search-local ^1.1.0

@docusaurus/core ^3.0.1

@docusaurus/preset-classic ^3.0.1

@docusaurus/theme-mermaid ^3.0.1

@mdx-js/react ^3.0.0

gray-matter ^4.0.3

prism-react-renderer ^2.3.0

react ^18.2.0

react-dom ^18.2.0

@docusaurus/tsconfig ^3.0.1

@types/react ^18.2.45

@docusaurus/types 3.3.2

@docusaurus/module-type-aliases ^3.0.1

typescript 5.4.5

node >=18

@docusaurus/core ^3.0.1