Skip to main content

Website

This section covers how to start developing on the website of the downscaler.

If you haven't already, read and follow the instructions for setting up the repository locally.

Installing Prerequisite​

Before being able to develop on the website you need to install some prerequisites.

Installing Npm​

NPM is required to be able to install the required packages to start the website.

You can either use brew to install npm:

brew install node

Or you can install it another way.

To check if the installation was successful you can run:

node -v

and

npm -v

The output should be something like:

v22.6.0

for node and

10.8.2

for npm.

Installing Dependencies​

After npm is installed you can install the websites dependencies.

npm install --prefix website

Updating Dependencies​

After pulling new commits that changed package.json you should update your node packages.

To update the dependencies you can use:

npm update --prefix website

Running the Website Locally​

Now that the prerequisites are installed you can start the website.

npm run --prefix website start

If you want to test features which are only available on the built site (e.g. search) use:

npm run --prefix website build && npm run --prefix website serve

This will disable hot reloads, so you will have to rerun the command every time you changed something to see it on the site.

Starting Development​

The following section covers the basics of how to make changes to the website. You can find more information on configuring this site in the official docusaurus documentation.

All files for the website can be found in ./website.

Adding/Changing Pages and Categories​

The website is built using Docusaurus which allows for documentation/guides pages to be markdown or mdx files. The markdown files are located in ./website/content/guides and ./website/content/docs.

Pages​

You can edit a page just by editing its mdx file. You can find information on markdown and MDX syntax on the docusaurus website.

To add a new page you can just add a .mdx file into any of the existing folders. Docusaurus will automatically build the changes and add the file as an entry into the sidebar.

Categories​

You can add categories by adding folders in the guides or docs folders. Categories don't have an index by default, so you will need to create one.

You can do this by creating an index.mdx file within the folder of the category. You could either just put a category description in them or fill them up with content themselves. Either way you should present the user with the items in the category with a DocCardList:

index.mdx
---
title: Some Category Title
id: some-category
---

import DocCardList from "@theme/DocCardList";

# Some Category Title

Some category description

{/* Optional Main content for the category */}

## Overview

<DocCardList />

The structure of the guides and docs is basically the same as on the built website. Folders are categories, mdx files are pages. Category indexes are the index.mdx files located in the folders of their respective categories.

The order in the sidebar is defined by number prefixes:

  • 0 - First Document (you could also start with 1)
  • 1 - Second Document
  • 2 - Third Document
  • n - nᵗʰ Document

External Sites​

Links to external sites are just normal markdown syntax: [some text](https://example.com)

Heading​

The same counts for links to a heading on the same page: [some text](#heading-id)

Github GoKubeDownscaler Repository​

To link to a file in the repository you can use the repo: directive:

  • [some text](repo:path/to/file)
  • [some text](repo:/path/to/file)
  • [some text](repo:./path/to/file)

-> https://github.com/caas-team/GoKubeDownscaler/tree/main/path/to/file

Another Guide or Documentation​

To link to another doc or guide, you first have to define a globalReference for that document. To do that you just have to add the globalReference attribute to the frontmatter of the document:

---
title: Example
id: example
globalReference: docs-example
---

after which you can use the reference to link to the document from any other:

Some [example](ref:docs-example) text.
note

If you added the link reference in the mdx file before adding the globalReference parameter to the frontmatter docusaurus might not rebuild your page until you either re-save your file to initiate a rebuild or clear the docusaurus cache.

Assets​

Assets like PNGs, SVGs, Excalidraw or other files can be useful to have in documentation.

Assets should be placed in an assets folder in the directory where it is being used.

Images​

![Alt Text](./assets/example.png)

SVGs​

{/* imports should be at the top of the file */}
import ExampleSvg from "./assets/example.svg";

<ExampleSvg />;

Files​

[Click to Download](./assets/example.txt)

This will create a hyperlink with the given text and when clicked this will download or open the file (depending on filetype).

Excalidraw Files​

For embedding .excalidraw files you need to use our custom Excalidraw component.

Additional Components​

We use mdx to be able to spice up the plain markdown a bit. For this purpose we have some custom additional components.

Github Label​

The Github label component is very useful when talking about the Github Labels for the GoKubeDownscaler project.

They can be any of the GoKubeDownscalers Labels and look just like the labels on Github. When clicked on they send the user to a view where they can see all issues and pull requests with that label.

Usage:

{/* imports should be at the top of the file */}
import { GithubLabel } from "/src/components/GithubLabel.tsx";

The <GithubLabel label="question" /> label.

Examples:

enhancement bug help wanted question

Excalidraw​

The Excalidraw component is useful when you need to explain something more complex with a diagram.

The Excalidraw component can render any excalidraw file. You can create and edit these either using their website or an extension for your IDE.

Usage:

{/* imports should be at the top of the file */}
import Excalidraw from "/src/components/Excalidraw/Excalidraw.tsx";
import exampleDiagram from "./assets/example.excalidraw";

<Excalidraw data={exampleDiagram} className="w-1/3" />

Example:

Loading...

Best Practices​

These are a collection of best practices you should be aware of:

  • avoid click here links
  • try to reduce the use of inline-html elements to a minimum
  • avoid too small headings (keep it under h5 and try to avoid h4)
  • don't nest sidebar categories (no categories in a category in a category)
  • use title case for headings
  • only put one sentence per line (a sentence can stretch across multiple lines)
  • try to split sentences so that when read in plain text it's easy to follow
  • the parts of split sentences should also all roughly be the same length
info

Some of these best practices and even more not listed here are enforced by some linters. It is best if you have pre commit installed so that it will tell you or fix the problems automatically.

It might also be worth looking into a markdown lint extension that supports MDX for your IDE. It will tell you what you can improve right in the editor itself.

Troubleshooting​

Sometimes the website looks broken/not how you expected, has errors or won't start/open. In these cases you have probably tried loads of things to get it working again. These are some of the most common fixes for such issues.

Clear Docusaurus Cache​

Docusaurus caches most files and doesn't rebuild them until they themselves change (e.g. rendered markdown files, SVGO/SVGR optimized SVGs, etc.). This can lead to problems when there are custom external dependencies which don't trigger a rebuild.

This command forces docusaurus to clear its cache and rebuild all files on the next start.

npm run --prefix website docusaurus clear

(Re-)Install Packages​

There are multiple reasons why reinstalling NPMs packages might fix some issues. Some of the most common reasons could be:

  • corrupted modules
  • outdated packages (npm update could also resolve this)
  • ...
rm -rf ./website/node_modules
npm install --prefix website