Skip to content

chongyouquan/website

 
 

Repository files navigation

Creating and updating the Kubeflow docs

Welcome to the GitHub repository for Kubeflow's public website. The docs are hosted at https://www.kubeflow.org.

We use Hugo to format and generate our website, the Docsy theme for styling and site structure, and Netlify to manage the deployment of the site. Hugo is an open-source static site generator that provides us with templates, content organization in a standard directory structure, and a website generation engine. You write the pages in Markdown, and Hugo wraps them up into a website.

Quickstart

Here's a quick guide to updating the docs. It assumes you're familiar with the GitHub workflow and you're happy to use the automated preview of your doc updates:

  1. Fork the kubeflow/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 can also add /hold in a comment to mark the PR as not ready for merge. (Don't add the Hugo property "draft = true" to the page front matter, because that prevents the auto-deployment of the content preview described in the next point.) See the Prow guide for help with the commands that you can use in a PR comment.
  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. Click Details 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 the Kubeflow contributor guide.

If you need more help with the GitHub workflow, follow this guide to a standard GitHub workflow.

Previewing your changes on a local website server

If you'd like to preview your doc updates as you work, you can install Hugo and run a local server to host your website. This section shows you how.

Install Hugo and other dependencies

You need Hugo version 0.80 or later, and it must be the extended version of Hugo. Hugo version 0.80 and later support the Goldmark renderer for Markdown. Goldmark offers improved rendering of some text formatting such as lists.

Note: From April 2020 onwards, Kubeflow recommends that you use Hugo version 0.83.1 or later. The Kubeflow website now uses Hugo 0.83.1 via Netlify.

To get the latest extended version of Hugo:

  1. Go to the Hugo releases page.
  2. In the most recent release, scroll down until you find a list of extended versions.
  3. Download the relevant file for your operating system.
  4. Unzip the downloaded file into a location of your choice.

For example, to install Hugo on Linux:

  1. Download hugo_extended_0.83.1_Linux-64bit.tar.gz (or the latest version) from the Hugo releases page.

  2. Create a new directory:

    mkdir $HOME/hugo
    
  3. Extract the file you downloaded to $HOME/hugo.

    tar -zxvf hugo_extended_0.83.1_Linux-64bit.tar.gz
    

For more details about installing Hugo, See the Hugo installation guide.

If you plan to make changes to the site styling, you need to install some CSS libraries as well. Follow the instructions in the Docsy theme's setup guide.

Fork and clone the website repository and run a local website server

Follow the usual GitHub workflow to fork the repository on GitHub and clone it to your local machine, then use your local repository as input to your Hugo web server:

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

  2. Clone your fork locally. This example uses SSH cloning:

    mkdir kubeflow
    cd kubeflow/
    git clone git@github.com:<your-github-username>/website.git
    cd website/
    
  3. Start your website server. Make sure you run this command from the /website/ directory, so that Hugo can find the config files it needs:

    hugo server -D