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)

Publishing

Hugo compiles the files under site Hugo 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  

Add the site/ and docs/ folders to a commit, then create a PR.

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

Raising a PR for changes in the site

  • Once deployed, you’ll have a URL pointing to the newly deployed site. Submit the URL along with the PR.
  • Make sure your changes are working as expected in the newly received netlify URL before PR.

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 November 11, 2020: outstanding issues fix (711e830)