Clipper Website

This contains the sources for building the Clipper website, hosted at http://clipper.ai.

First clone the repository and it's submodules.

git clone --recursive https://github.com/ucbrise/clipper-website.git

The website is built with Hugo, a static site generator. You should read at least the Hugo quickstart, but here's how to get the website built and running quickly

To build the website, you need to first install Hugo.

brew install hugo

Once you do that, you can build and serve the website locally by running the following command in the root of the repo.

hugo server

You can see the website at http://localhost:1313/. Hugo will automatically detect and rebuild the website when you change any files.

Editing content

The website content is all stored in the content/ subdirectory in markdown files. The website is organized into chapters, the sources for each chapter are stored in their own subdirectory in content/. For example, all of the entries for the overview chapter are stored in content/overview/.

~/clipper-website|master $  tree -a content/overview
content/overview
├── _index.md
├── quickstart.md
├── tutorial.md
└── user_guide.md

0 directories, 4 files

To edit any existing page, just edit the markdown file. You can read more about how chapters work and some custom markdown extensions (e.g. shortcodes) at the theme website.

Adding content

To add a new chapter, run the following command from the root of the website repo. Note that Hugo automatically knows to create the directory in the content/ subdirectory, you don't need to specify it.

hugo new --kind chapter <your_chapter_name>/_index.md

This will create a directory for the chapter and the chapter overview page. If you would like to create a chapter with only a single page (and therefore no overview page), set chapter = false in the _index.md frontmatter. See content/querying_clipper/_index.md for an example of a single-page chapter.

To add a new page to an existing chapter, run the following command.

hugo new <existing_chapter_name>/<my_new_chapter_entry_name.md>

The order of both chapters and content within a chapter is controlled by the weight field in the frontmatter. You can think of weights as assigning relative page numbers, higher weighted pages go after lower weight pages.

You can add static resources (like images) in the static/ directory. Please add the resource to the appropriate static/ subdirectory (e.g. images should go in static/images/). If you don't see a directory that fits, feel free to create one.

Editing the theme

The CSS and html templates are all part of the Hugo theme we are using, you can edit them by editing the appropriate files in themes/hugo-theme-learn/. If you're not sure where things are or how to edit them, ask Dan.

Building the website

Once you've made your changes and tested them locally, submit a pull request. Once they've been merged into master, the new version of the site can be published with the publish_site.sh script. From a freshly pulled and clean checkout of master, run ./publish_site.sh <remote_repo_name>. For example, if the name of your remote repo was ucbrise, run the following commands from the root of the clipper-website repo.

git checkout master
git pull --rebase ucbrise master
./publish_site.sh ucbrise

You can read about how the publish_site.sh script works here.