New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Website guide #143

Merged
merged 5 commits into from Aug 13, 2018
View
168 README.md
@@ -1,30 +1,168 @@
# website
Kubeflow's public website
# Creating and updating the Kubeflow docs
## Development
Welcome to the GitHub repository for Kubeflow's public website. The docs are
hosted at https://www.kubeflow.org.
### Getting started
macOS...sorry :-)
We use [Hugo](https://gohugo.io/) to format and generate our website. Hugo is
an open-source static site generator that provides us with templates, content
organisation in a standard directory structure, and a website generation engine.
You write the pages in Markdown, and Hugo wraps them up into a website.
`brew install hugo`
## Install Hugo
`hugo serve -D`
See the [Hugo installation guide][hugo-install]. Here are some examples:
### New content
`hugo new blog/another-blog-post.md`
### Mac OS X:
`hugo new doc/add-this-doc.md`
```
brew install hugo

This comment has been minimized.

@jlewi

jlewi Aug 10, 2018

Contributor

Why go to the trouble of running hugo locally? If users want to do a preview they can just create a PR and we will automatically generate a preview they can look at?

If the PR isn't ready for review they can just mark it WIP.

Can we add this as an alternative path and make it clear that its less work?

@jlewi

jlewi Aug 10, 2018

Contributor

Why go to the trouble of running hugo locally? If users want to do a preview they can just create a PR and we will automatically generate a preview they can look at?

If the PR isn't ready for review they can just mark it WIP.

Can we add this as an alternative path and make it clear that its less work?

This comment has been minimized.

@sarahmaddox

sarahmaddox Aug 11, 2018

Contributor

I see. I didn't know we automatically generate a preview. How/where can I see that preview? I guess that may become clear the first time I submit a PR for a web page, but as someone putting together my first website PR I had no idea that will happen. I therefore assumed I had to run my own Hugo server. I've spent quite some time reading the Hugo docs, and then figuring out how to fit them into our own situation. It'd be good to help others avoid doing the same work, by adding this info to the guide.

@sarahmaddox

sarahmaddox Aug 11, 2018

Contributor

I see. I didn't know we automatically generate a preview. How/where can I see that preview? I guess that may become clear the first time I submit a PR for a web page, but as someone putting together my first website PR I had no idea that will happen. I therefore assumed I had to run my own Hugo server. I've spent quite some time reading the Hugo docs, and then figuring out how to fit them into our own situation. It'd be good to help others avoid doing the same work, by adding this info to the guide.

This comment has been minimized.

@sarahmaddox

sarahmaddox Aug 11, 2018

Contributor

I'll figure out how the generated preview happens for a PR, and include it in this update.
/hold

@sarahmaddox

sarahmaddox Aug 11, 2018

Contributor

I'll figure out how the generated preview happens for a PR, and include it in this update.
/hold

This comment has been minimized.

@sarahmaddox

sarahmaddox Aug 11, 2018

Contributor

OK, I've figured out I should probably add "draft = true" to the page front matter, to indicate to Hugo that this is a draft. Done that. But even after reading all the Hugo docs and our config files, I can't figure out what the URL is where the draft matter should show up. Please would you ping me the URL? In case it's useful, here's my PR with draft content: #151

@sarahmaddox

sarahmaddox Aug 11, 2018

Contributor

OK, I've figured out I should probably add "draft = true" to the page front matter, to indicate to Hugo that this is a draft. Done that. But even after reading all the Hugo docs and our config files, I can't figure out what the URL is where the draft matter should show up. Please would you ping me the URL? In case it's useful, here's my PR with draft content: #151

```
### Debian:
1. Download the latest Debian package from the [Hugo website][hugo-install].
For example, `hugo_0.46_Linux-64bit.deb`.
1. Install the package using `dpkg`:
```
sudo dpkg -i hugo_0.46_Linux-64bit.deb
```
1. Verify your installation:
```
hugo version
```
## Clone the website repo from GitHub and run a local website server
Follow the usual GitHub workflow to fork the repo on GitHub and clone it to your
local machine, then use your local repo as input to your Hugo web server:
1. **Fork** the repo in the GitHub UI.
1. Clone your fork. This example uses SSH cloning:
```
mkdir kubeflow
cd kubeflow/
git clone git@github.com:<your-github-username>/website.git
cd website/
```
1. 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
```
1. Your website is at [http://localhost:1313/](http://localhost:1313/).
1. Continue with the usual GitHub workflow to edit files, commit them, push the
changes up to your fork, and create a pull request. (See below.)
1. While making the changes, you can preview them on your local version of the
website at [http://localhost:1313/](http://localhost:1313/).
Here's a quick guide to the GitHub workflow plus a bit of Hugo for
creating/editing pages:
1. Add the upstream repo as remote:
```
git remote add upstream https://github.com/kubeflow/website.git
```
1. Check your remotes:
```
git remote -vv
```
### Making changes to CSS
You should have 2 remote repos:
- `origin` - points to your own fork of the repo on gitHub -
that is, the one you cloned my local repo from.
- `upstream` - points to the actual repo on gitHub.
1. Create a branch - replace `doc-updates` with any branch name you like:
```
git checkout -b doc-updates
```
1. Add and edit the files as you like. The doc pages are in the
`/website/content/docs/` directory.
1. To add a page using Hugo, go to the `/website/` directory so that Hugo can
find its config files, then use `hugo new` to add the page:
```
cd /website/
hugo new <path/to/doc>/add-this-doc.md
```
Example:
```
hugo new content/docs/guides/add-this-doc.md
```
1. As you work, you can see your changes on your local website at
[http://localhost:1313/](http://localhost:1313/). Note that if you have more
than one local git branch, when you switch between git branches the local
website reflects the pages as they are in your current branch.
1. Commit your updated files to your local git repo. Example commit:
```
git commit -a -m "Fixed some doc errors."
```
Or:
```
git add add-this-doc.md
git commit -a -m "Added a shiny new doc."
```
1. Push from your branch (for example, `doc-updates`) to **the relevant branch
on your fork on GitHub:**
```
git checkout doc-updates
git push origin doc-updates
```
1. When you're ready to start the review process, create a pull request (PR)
**in the branch** on **your fork** on the GitHub UI, based on the above push.
The PR is auto-sent to the upstream repo - that is, the one you forked from.
1. If you need to make changes to the files in your PR, continue making them
locally in the same branch, then push them again in the same way. GitHub
automatically sends them through to the same PR on the upstream repo!
1. **Hint:** If you're authenticating to GitHub via SSH, use `ssh-add` to add
your SSH key passphrase to the managing agent, so that you don't have to
keep authenticating to GitHub. You need to do this again after every reboot.
## Links
- Useful Hugo docs
- [Hugo quickstart](https://gohugo.io/getting-started/quick-start/)
(not very relevant, because we already have a site)
- [Hugo installation guide][hugo-install]
- [Hugo basic usage](https://gohugo.io/getting-started/usage/)
- [Hugo site directory structure](https://gohugo.io/getting-started/directory-structure/)
- [hugo server](https://gohugo.io/commands/hugo_server/) reference
- [hugo new](https://gohugo.io/commands/hugo_new/) reference
- [Kubeflow generic contributor guide](https://github.com/kubeflow/community/blob/master/CONTRIBUTING.md)
## Making changes to CSS
The css/sass style code is located in the `themes/kf/sass` directory.
#### CSS Dev Setup
You'd need to install node.js. Download the binary for your platform
### CSS Dev Setup
You need to install node.js. Download the binary for your platform
[here](https://nodejs.org/en/download/). This will also install npm.
#### Updating theme style
### Updating theme style
If you need to make changes to the style, you can update the theme's style using:
@@ -57,3 +195,5 @@ using the version shortcode, 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.
[hugo-install]: https://gohugo.io/getting-started/installing/
ProTip! Use n and p to navigate between commits in a pull request.