Coo template

This is a template for using the Jekyll theme Coo to create online documentation. Coo is a fork of the Jekyll theme Chirpy with some modifications to make it easy for creating online documentation. This template is based on the Chirpy starter template. You might find the Chirpy documentation useful to help you get started on Chirpy.

Prerequisites

The Jekyll project has detailed instruction on how to setup Jekyll and Ruby. Git is required as part of your development environment. You might find GitHub Desktop (or its Linux version) to be a friendly graphical interface to Git and GitHub.

Installation

Ruby and Jekyll

Sign into GitHub and navigate to the template home page. Click on Use this template, then click on Create a new repository to create a repository based on the template. Use Git or GitHub Desktop to clone your newly created repository to your local machine. At the top-level directory of the repository, run the command:

$ bundle

The above assumes root access. Without root access, you would not be able to install Ruby gems in the system-wide directory. That is OK. Use the commands below to install all required gems under the top-level directory of the repository.

$ bundle config set --local path 'vendor/bundle'
$ bundle install

The above commands would setup the Ruby and Jekyll environment for your repository.

Make

The software Make is recommended, but not required, to automate the building of your site. Under a Linux environment, you might want to install GNU Make. On Windows, install Make as part of the Cygwin environment.

Feel free to use a build automation utility of your choice.

npm (optional)

The package you want is Prettier, which can automatically indent and format Markdown files. Feel free to use another tool to lint/format/indent the Markdown files in your project. Run the following command to install all node packages required by this template:

$ npm update

Usage

See the website of the template. You might also find the documentation of the Chirpy template useful.

Configuration

See the file _config.yml.

Home page

At the top-level directory of your repository, create a file called index.html if it does yet exist. This is the first page that shows up when someone visits your site. See the index page of tekyll for an example.

Contents

Sections or chapters

To start writing contents for your site, create a directory named doc/ (if it does not yet exist) at the top-level directory of your repository. All textual contents for your document should be placed under the directory doc/. Each section or chapter of your entire document should be a separate Markdown file. Refer to the directory doc/ of tekyll for sample contents.

Summary

You also need to create a YAML file called _data/summary.yml (if it does not yet exist). Note that the summary must be located under the directory _data/. The summary file shows the structure of your entire document. In particular:

• The summary file shows the location of each section or chapter of your document. Recall that each section or chapter should be a separate Markdown file located under the directory doc/.
• The summary file shows the order in which each section or chapter should appear when you build your site. The ordering of the section/chapter will be used to generate the table of contents in the sidebar.

Refer to the summary file of tekyll for an example.

Images

Images should be placed under assets/img/ (the default directory used by tekyll) or another location of your choice. If you use a content delivery network (CDN) for images, ensure you set the URL of the CDN in the file _config.yml. The images used by the tekyll site are hosted by GitHub, as can be seen in the following lines of the configuration file shipped with tekyll:

# The CDN endpoint for images.
# Notice that once it is assigned, the URL of the CDN will be added to all
# image (site avatar and images of each page) paths starting with '/'.
#
# e.g. 'https://cdn.com'
img_cdn: https://raw.githubusercontent.com/quacksouls/tekyll/main/assets/img/

Build

Feel free to use a build automation utility of your choice. The default build automation tool used by this Jekyll template (i.e. tekyll) is Make. The description below refers to the Makefile shipped with tekyll.

The Makefile controls all aspects of the build process. Refer to the Makefile of tekyll for an example. The following explains how the Makefile of tekyll works. Note that the Makefile uses scripts under the directory util/.

• build -- This builds a local copy of your entire site. Use the command:

  $ make build
  

  to build your local copy.

• clean -- Cleanup various junk files. Use the command:

  $ make clean
  

  to perform the cleanup.

• pretty -- Use Prettier to automatically format and indent Markdown files. Use the command:

  $ make pretty
  

  to run Prettier on the Markdown files under doc/.

• view -- Useful for viewing a draft of your site on your local machine. This builds a local copy of your entire site. It also starts a local web server to allow you to view your site on your local machine. Use the command:

  $ make view
  

  to build a local copy of your site and start a local server. Open a web browser and navigate to the address http://127.0.0.1:4000 to view your site.

License

This work is covered by the MIT license. It is based on the Chirpy template by:

Copyright (c) 2021 Cotes Chung

Modification by:

Copyright (c) 2023 Duck McSouls