Documentation

How to make contributions to this site

This site uses Docsy and was forked from the docsy-example

Prerequisites

  • Install hugo
  • Clone kustomize
    • git clone git@github.com:kubernetes-sigs/cli-experimental && cd site/

Development

The doc input files are in the site directory. The site can be hosted locally using hugo server.

cd site/
npm install
npm install -g postcss-cli
npm install autoprefixer
npm audit fix
hugo server
...
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

Making a PR with your changes

Once you’ve verified that your changes look good using the local Hugo server, compile the HTML to be committed.

  1. Run the hugo command. This compiles the files under site into HTML, which it puts in the docs folder:
cd site/
hugo
                   | EN  
-------------------+-----
  Pages            | 99  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     | 47  
  Processed images |  0  
  Aliases          |  2  
  Sitemaps         |  1  
  Cleaned          |  0  
  1. Commit the changes to both the site/ and docs/ folders.

  2. Open a PR.

  3. Once status checks run on your PR, look for the deploy/netlify status check, and click the Details link to verify your change on Netlify.

Netlify Preview PR Status Image

Publishing docs in forked repository

We use Netlify to publish changes in the site. You can also enable netlify on you’re forked repo by doing the following step.

  • Log into Netlify using your Github Credentials.
  • Click New Site from Git button in the Netlify Dashboard.
  • The setup has 3 steps.
    • Connect to Git Provider - Select Github here and authenticate your Github account if not done earlier.
    • Pick a repository - Select the forked repository here.
    • Build options, and deploy! - Here set Branch to deploy to the branch that has the latest changes also set Publish directory to ./docs.

Netlify Setup Image

Once deployed, you’ll have a URL pointing to the newly deployed site.

Netlify Deployed Image

Setting Custom Domain & DNS changes

  • Make sure you’re a part of Kubernetes Docs Netlify team.
  • Under Site Settings you’ll find Domain Management, where in you can set the site’s custom domain.
  • Ideally, it should match up with the wild card *.k8s.io
  • Once custom domains are set on Netlify, you can raise a PR in k8s.io github repository.
  • You’ll have to add this snippet in dns/zone-configs/k8s.io._0_base.yaml file:
# <github repo url> (@maintainers)
<custom_name>:
  type: CNAME
  value: <current_netlify_url>.


Last modified January 18, 2022: Update readme and contributing docs (0d2b128)