Skip to content

Commit

Permalink
doc rewrites and formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
@datvance
datvance committed Jan 9, 2020
1 parent 3c610d7 commit 63d260d
Showing 1 changed file with 26 additions and 22 deletions.
48 changes: 26 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,38 @@
# Koru-Jekyll
# Koru-Jekyll Template

Koru-Jekyll is a [Jekyll](https://help.github.com/en/github/working-with-github-pages/about-github-pages-and-jekyll) theme for [Github Pages](https://help.github.com/en/github/working-with-github-pages), based on UCAR/NCAR's custom 'Koru' design, and using the same templates, colors, fonts, etc as the main [NCAR](https://ncar.ucar.edu) and [UCAR](https://www.ucar.edu) Umbrella sites. Essentially, Github Pages is a static website server built in to every Github repository (you need to enable it in your repo, it is off by default). GitHub Pages serves static HTML, CSS, JS, images, PDFs, text files, etc, but does not support dynamic scripting languages like PHP, Perl, Python, etc. [Jekyll](https://jekyllrb.com/) is a static site generator built in to Github Pages to allow you to generate HTML and static assets from Markdown files. Koru-Jekyll is developed and supported by SWES in CISL.
This repository is an example repo that any NCAR or UCAR staff or project can use as a starting point for their own GitHub Pages site. Essentially, GitHub Pages is a static website server built in to every GitHub repository. GitHub Pages serves static HTML, CSS, JS, images, PDFs, text files, etc, but does not support dynamic scripting languages like PHP, Perl, Python, etc.

## Using Koru-Jekyll
Koru-Jekyll Template uses the [Koru-Jekyll](https://github.com/NCAR/koru-jekyll) theme, which is based on UCAR/NCAR's custom 'Koru' design, utilizing the same templates, colors, fonts, etc as the main [NCAR](https://ncar.ucar.edu) and [UCAR](https://www.ucar.edu) Umbrella sites. Koru-Jekyll is implemented as a [Jekyll](https://jekyllrb.com/) theme. Jekyll is a static site generator [built in to GitHub Pages](https://help.github.com/en/github/working-with-github-pages/about-github-pages-and-jekyll) to allow you to generate HTML and static assets from Markdown files.

Koru-Jekyll is built on top of the [Foundation for Sites](https://foundation.zurb.com/sites.html) HTML framework. This provides users and developers with responsiveness and accessibility. Content can be written in Markdown or HTML. Some familiarity with Git/Github and HTML/Markdown is beneficial, but not necessary.
Koru-Jekyll and Koru-Jekyll Template are developed and supported by SWES in CISL.

* [Setup](#Setup)
* [Layouts](#layouts)
* [Main Menu](#main-menu)
* [Local Development](#local-development)
## Using Koru-Jekyll Template for a Static Website

Koru-Jekyll is built on top of the [Foundation for Sites](https://foundation.zurb.com/sites.html) HTML framework. This provides users and developers with responsiveness and accessibility. Content can be written in Markdown or HTML. Some familiarity with Git/GitHub and HTML/Markdown is beneficial, but not necessary.

## Setup
### Using a New Repo

You can serve a GitHub Pages site from a new or existing repository.

### Using a New Repository

* Click the "Use this template" button in the GitHub interface of this repo
* On the ensuing screen:
* Choose "NCAR" as the owner
* Enter a unique Repository name for your repo
* Note: The repo name you choose will be used in the GitHub Pages URL e.g. ncar.github.io/your-repo-name/
* Later, you can configure a Custom Domain (e.g. my-project.ucar.edu) for your new GitHub Pages site as well
* Later, you can configure a Custom Domain (e.g. my-project.ucar.edu) for your new GitHub Pages site
* Select the "Public" option
* Click the "Create a new respository" button and wait for GitHub to generate your new repo
* Once your new repo has been created, you need to enable GitHub Pages:
* Click the "Create respository from template" button and wait for GitHub to generate your new repo
* Once your new repo has been created, you need to enable GitHub Pages within it:
* Click the "Settings" tab in the top right
* Scroll down to the "GitHub Pages" section
* For Source, choose "Master Branch" (learn more about [publishing sources](https://help.github.com/en/github/working-with-github-pages/about-github-pages#publishing-sources-for-github-pages-sites))
* For Source, choose "master branch" (learn more about [publishing sources](https://help.github.com/en/github/working-with-github-pages/about-github-pages#publishing-sources-for-github-pages-sites))
* Ignore the "Choose a theme" button. Your theme (Koru-Jekyll) is configured in the _config.yml file of your new repo
* Your new site should now be published at https://ncar.github.io/your-repo-name/

### Using an Existing Repo
### Using an Existing Repository

First, decide where to house the [publishing source](https://help.github.com/en/github/working-with-github-pages/about-github-pages#publishing-sources-for-github-pages-sites) in your repo. You can choose the master branch, a "gh-pages" branch, or a "/docs" folder in your master branch. This is where the source files for your website will live. As an example, let's choose a "/docs" folder in the master branch:

* Create a /docs directory in the master branch of your repo
Expand All @@ -39,15 +43,15 @@ First, decide where to house the [publishing source](https://help.github.com/en/
* Enable GitHub Pages in you repo:
* Click the "Settings" tab in the top right
* Scroll down to the "GitHub Pages" section
* For Source, choose "/docs" (learn more about [publishing sources](https://help.github.com/en/github/working-with-github-pages/about-github-pages#publishing-sources-for-github-pages-sites))
* For Source, choose "master branch /docs folder" (learn more about [publishing sources](https://help.github.com/en/github/working-with-github-pages/about-github-pages#publishing-sources-for-github-pages-sites))
* Ignore the "Choose a theme" button. Your theme (Koru-Jekyll) is configured in the _config.yml file of your new repo
* Your new site should now be published at https://ncar.github.io/your-repo-name/

## Creating Content

As mentioned above, GitHub Pages is just a static website server, so any files you place in your repo within your publishing source will be served from your website. Jekyll automatically generates HTML files from Markdown files, based on the Koru-Jekyll theme.
As mentioned above, GitHub Pages is just a static website server, so any files you place in your repo within your publishing source will be served from your website.

* GitHub Pages automatically converts markdown to HTML and serves it from your website
* Using Jekyll, GitHub Pages automatically converts Markdown to HTML, based on the Koru-Jekyll theme, and serves it from your website
* For instance, the [Home page](https://ncar.github.io/koru-jekyll-template/index.html) of this repo is the [index.md](./index.md) Markdown file and the [Support page](https://ncar.github.io/koru-jekyll-template/pages/support.html) can be found at [support.md](./pages/support.md)
* GitHub Pages will automatically re-generate HTML pages from Markdown on each commit
* You can create as many Markdown files as you want, in any directory structure. A /pages directory is provided by default
Expand Down Expand Up @@ -86,7 +90,7 @@ banner-button-url:
---
```

## Updating the main menu
## Updating the Main Menu

The main menu is set in the mainmenu.yml file in the _data directory. Paths can be either absolute or relative in the menu. The structure for creating a menu is:

Expand All @@ -102,7 +106,7 @@ When developing locally, you will need to remove the repository name from the UR

## Local Development and Site Preview

There is no "preview" facility in GitHub Pages. You will need to stand up your site locally instead, and a Docker container is provided for this in the repo. You will need Docker installed on your local computer.
There is no "preview" facility in GitHub Pages. You will need to stand up your site locally instead, and a Docker container is provided for this in the repo. You will need [Docker installed](https://docs.docker.com/) on your local computer.

Run `docker-compose up --build` to (re)build the jekyll images and run the container.

Expand All @@ -125,12 +129,12 @@ SWES occasionally pushes out updates to the Koru-Jekyll theme. To apply those ch
### Jekyll Docs
* [Getting Started](https://jekyllrb.com/docs/)

### Github Docs
* [Github Pages Basics](https://help.github.com/en/categories/github-pages-basics)
### GitHub Docs
* [GitHub Pages Basics](https://help.github.com/en/categories/github-pages-basics)
* [Jekyll on GitHub Pages](https://help.github.com/en/github/working-with-github-pages/about-github-pages-and-jekyll)
* [Jekyll Docs](https://jekyllrb.com/docs/)
* [Mastering Markdown](https://guides.github.com/features/mastering-markdown/)
* [Repository metadata on Github](https://help.github.com/en/articles/repository-metadata-on-github-pages)
* [Repository metadata on GitHub](https://help.github.com/en/articles/repository-metadata-on-github-pages)

### Sphinx and Jekyll

Expand Down

0 comments on commit 63d260d

Please sign in to comment.