Repository files navigation

Welcome to the GitHub repository for Kubeflow's public website!

The docs website is hosted athttps://www.kubeflow.org.

We useHugo with thegoogle/docsytheme for styling and site structure, andNetlify to manage the deployment of the site.

Here's a quick guide to updating the docs:

1. Fork thekubeflow/website repository on GitHub.

2. Make your changes and send a pull request (PR).

3. If you're not yet ready for a review, add "WIP" to the PR name to indicate it's a work in progress.Alternatively, you use the/holdprow command in a comment to mark the PR as not ready for merge.

4. Wait for the automated PR workflow to do some checks.When it's ready, you should see a comment like this:deploy/netlify — Deploy preview ready!

5. ClickDetails to the right of "Deploy preview ready" to see a preview of your updates.

6. Continue updating your doc and pushing your changes until you're happy with the content.

7. When you're ready for a review, add a comment to the PR, remove any holds or "WIP" markers, and assign a reviewer/approver.See theKubeflow contributor guide.

If you need more help with the GitHub workflow, followthisguide to a standard GitHub workflow.

This section will show you how to develop the website locally, by running a local Hugo server.

To install Hugo, follow theinstructions for your system type.

NOTE: we recommend that you use Hugo version0.124.1, as this is currently the version we deploy to Netlify.

For example, using homebrew to install hugo on macOS or linux:

# WARNING: using `brew install hugo` will install the latest version of hugo#          which may not be compatible with the website# TIP: to install hugo run the following commandsHOMEBREW_COMMIT="9d025105a8be086b2eeb3b1b2697974f848dbaac"# 0.124.1curl -fL -o"hugo.rb""https://raw.githubusercontent.com/Homebrew/homebrew-core/${HOMEBREW_COMMIT}/Formula/h/hugo.rb"brew install ./hugo.rbbrew pin hugo

If you plan to make changes to the site styling, you need to install somenode libraries as well.(See theDocsy setup guide for more information)

You can install the same versions we use in Netlify (defined inpackage.json) with the following command:

npm install -D

Follow the usual GitHub workflow of forking the repository on GitHub and then cloning your fork to your local machine.

1. Fork thekubeflow/website repository in the GitHub UI.

2. Clone your fork locally:

   git clone git@github.com:<your-github-username>/website.gitcd website/

3. Initialize the Docsy submodule:

   git submodule update --init --recursive

4. Install Docsy dependencies:

   # NOTE: ensure you have node 18 installed(cd themes/docsy/&& npm install)

5. Start your local Hugo server:

   # NOTE: You should ensure that you are in the root directory of the repository.hugo server -D

6. You can access your website athttp://localhost:1313/

• User guide for the Docsy theme
• Hugo installation guide
• Hugo basic usage
• Hugo site directory structure
• hugo server reference

The site theme has one Hugo menu (main), which defines the top navigation bar. You can find and adjust the definitionof the menu in thesite configuration file.

The left-hand navigation panel is defined by the directory structure under thedocs directory.

Aweight property in thefront matter of each page determines the position of the page relative to the others in the same directory.The lower the weight, the earlier the page appears in the section.

Here is an example_index.md file:

+++title ="Getting Started with Kubeflow"description ="Overview"weight =1+++

We use theDocsy theme for the website.The theme files are managed with agit submodule in thethemes/docsy directory.

Do not change these files, they are not actually inside this repo, but are part of thegoogle/docsy repo.

To update referenced docsy commit, run the following command at the root of the repo:

# for example, to update docsy to v0.6.0# WARNING: updating the docsy version will require you to update our overrides#          check under: `layouts/partials` and `assets/scss`git -C themes/docsy fetch --tagsgit -C themes/docsy checkout tags/v0.6.0

For guidance on writing effective documentation, seethestyle guide for the Kubeflow docs.

The theme holds its styles in theassets/scss directory.

Do not change these files, they are not actually inside this repo, but are part of thegoogle/docsy repo.

You can override the default styles and add new ones:

• In general, put your files in the project directory structure underwebsite rather than in the theme directory.Use the same file name as the theme does, and put the file in the same relative position.Hugo looks first at the file in the main project directories, if present, then at the files under the theme directory.For example, the Kubeflow website'slayouts/partials/navbar.htmloverrides the theme'slayouts/partials/navbar.html

• You can update the Kubeflow website's project variables in the_variables_project.scss file.Values in that file override theDocsy variables.You can also use_variables_project.scss to specify your own values for any of the defaultBootstrap 4 variables.

• Custom styles_styles_project file

Styling of images:

• To see some examples of styled images, take a look at theOAuth setup page in the Kubeflow docs.Search for.png in thepage source.

• For more help, see the guide toBootstrap image styling.

• Also see the Bootstrap utilities, such asborders.

The site'sfront page:

• See thepage source.

• The CSS styles are in theproject variables file.

• The page uses thecover block defined by the theme.

• The page also uses thelinkdown block.

Sometimes it's useful to define a snippet of information in one place and reuse it wherever we need it.For example, we want to be able to refer to the minimum version of various frameworks/libraries throughout the docs,without causing a maintenance nightmare.

For this purpose, we use Hugo's "shortcodes".Shortcodes are similar to Django variables. You define a shortcode in a file, then use a specific markupto invoke the shortcode in the docs. That markup is replaced by the content of the shortcode file when the page is built.

To create a shortcode:

1. Add an HTML file in the/website/layouts/shortcodes/ directory.The file name must be short and meaningful, as it determines the shortcode you and others use in the docs.

2. For the file content, add the text and HTML markup that should replace the shortcode markup when the web page is built.

To use a shortcode in a document, wrap the name of the shortcode in braces and percent signs like this:

{{% shortcode-name %}}

The shortcode name is the file name minus the.html file extension.

Example: The following shortcode defines the minimum required version of Kubernetes:

• File name of the shortcode:

  kubernetes-min-version.html

• Content of the shortcode:

  1.8

• Usage in a document:

  You need Kubernetes version {{% kubernetes-min-version %}} or later.

Useful Hugo docs:

• Shortcode templates
• Shortcodes

For each stable release, we create a new branch for the relevant documentation.For example, the documentation for the v0.2 stable release is maintained in thev0.2-branch.Each branch has a corresponding Netlify website that automatically syncs each merged PR.

The versioned sites follow this convention:

• www.kubeflow.org always points to the currentmaster branch
• master.kubeflow.org always points to GitHub head
• vXXX-YYY.kubeflow.org points to the release at vXXX.YYY-branch

We also hook up each version to the dropdown on the website menu bar.

Whenever any documents reference any source code, you should use the version shortcode in the links, like so:

https://github.com/kubeflow/kubeflow/blob/{{< params "githubbranch" >}}/scripts/gke/deploy.sh

This ensures that all the links in a versioned webpage point to the correct branch.