README.md

February 1, 2023 · View on GitHub

CDK8s.io

landing page

:building_construction: Architecture

CDK8s.io is a static site split into two parts:

⚠️ Prerequisites

:rocket: Quick start

1. Install the Node dependencies

From the root of this repo (cdk8s/) run:

# Root of repo
yarn install

This will…

  • Install the latest release of the currently supported cdk8s-plus-* packages. We'll need this later to copy the doc files from each package into the cdk8s/docs/ directory.

2. Build the documentation pages

Run the build docs script:

# Root of repo
./docs/build.sh

This will…

3. Run the MkDocs server to preview the documentation content of the site.

# Root of repo
mkdocs serve

This should start the server at http://127.0.0.1:8000

4. (Optional) Run the Hugo server to preview the landing page

You'll need to have Hugo installed. Then in a new terminal run:

# Root of repo
cd website && hugo server && cd -

This should start the server at http://127.0.0.1:1313

Changes made to the docs content in cdk8s/docs/* will not be reflected in the Hugo server. You'll need to re-run the build docs script to see the changes or use the MkDocs server from step 3.

📦 Building the production site

1. Build the landing page.

# Root of repo
cd website && ./build.sh && cd -

2. Build the MkDocs pages and copy them to Hugo's public directory.

Run the build docs script:

# Root of repo
./docs/build.sh

The site's static files should now be available in the cdk8s/website/public/* directory ready for deployment.

:house: cdk8s.io landing page

The content of the landing page is maintained in cdk8s/website/config.yaml. You'll see the various sections, and some commentary from the theme authors on where images are loaded from.

Sections can be removed by simply omitting their section key from config.yaml.

The code for the landing page is located in cdk8s/website/static/js/webflow.js. However it is not recommended to edit this file. It was generated using Webflow and is difficult to read. It's source Webflow project is no longer available. This is obviously not an ideal implementation. It stands as one of the major justifications that a revamp is due for this website.

📖 cdk8s.io/docs/* pages

The documentation content is located in the cdk8s/docs/ directory. This content is written in Markdown and is built using MkDocs. Here are a few pointers to help save you time.

:heavy_plus_sign: Where do the cdk8s-plus-* docs come from?

In the cdk8s-plus repo, documentation from cdk8s-plus/docs/plus/* is included in the auto published NPM package. This way documentation can be version specific and easily maintained alongside the source code.

If you'd like to modify the content of any cdk8s-plus-* docs, you'll need to do so in the respective cdk8s-plus release branch.

e.g. To update the cdk8s-plus-24 docs you'll need to

  1. Commit changes to the cdk8s-plus/k8s-24/main branch.
  2. Wait for the release-k8s.24 GitHub workflow to auto publish a new NPM package.
  3. Bump this project's dependencies by running the cdk8s upgrade GitHub workflow.
  4. Re-run the yarn install and docs build script (see :rocket: Quick start section).

📄 Adding, removing, reordering or renaming pages

A .pages file can be used in each directory to describe the page structure of the site. This is a feature provided by the Awesome pages plugin. Check out their docs for more info.

To hide a file, omit the file from the parent directory's .pages file.

Notice how the README.md file that you're reading is located in the cdk8s/docs/ directory but it will not be included in the site unless we add it to the cdk8s/docs/.pages file.

🖼️ Assets and custom CSS

The cdk8s/docs/assets/ directory is to store assets that are used in the documentation (e.g. images). The cdk8s/docs/assets/extra.css is a file we've defined to apply custom CSS should you need it.

🔌 Plugins, features, and global configuration

The cdk8s/mkdocs.yaml file is used to define MkDocs configuration.

This is where you can define:

  • The logo
  • Site name
  • Favicon
  • Theme colors
  • Footer content
  • Extensions (e.g. multi-tab content block, table of content settings)
  • Plugins (e.g. search)

Check out the MkDocs config documentation for more info.

👨‍💻 Development resources

  • MkDocs material theme setup - This is the MkDocs theme that we use. This is also where you'll find APIs that enable you to customize the color theme, fonts, logo, and site search.
  • MkDocs material theme API - Create Admonitions, Annotations, Buttons, Code blocks, Content tabs, Icons, Images, and more.
  • MkDocs site config docs - Lists the global MkDocs configuration options that can be defined in cdk8s/mkdocs.yaml.
  • MkDocs plugin docs - Defines the plugin API that can be used to extend MkDocs.
  • Site search plugin docs - This is the search plugin we use and is where you'll find APIs that allow you to customize the search experience.
  • Awesome pages plugin docs - Used to define the page structure of the site using .pages files.