Changing This Documentation
See something out of date? A tpyo? Want to add more details that you wished were included when you first read these docs?
Great News! These docs are open source and we welcome pull requests to improve our documentation (ideas come from everyone, after all!)
Table of contents
Technical Details + External Documentation
This site is hosted on GitHub Pages, and uses Jekyll as a static site generator.
What is a static site generator?
From the Jekyll Docs: Jekyll is a static site generator. It takes text written in your favorite markup language and uses layouts to create a static website. You can tweak the site’s look and feel, URLs, the data displayed on the page, and more.
For a more technical explanation, see this page: Cloudflare - What is a static site generator?
Both GitHub and Jekyll have great documentation available:
Additionally, CodeDay uses a theme called Just the Docs. It’s often easiest to check the Just the Docs documentation first, and look at the GitHub Pages/Jekyll documentation if Just the Docs doesn’t have the answer. Just the Docs provides lots of helpful built-in features so we don’t need to worry very much about the more technical things covered in the GitHub Pages and Jekyll documentation.
Development Environment Setup
Running this site locally requires Ruby and Jekyll to be installed. Follow the Jekyll Installation Instructions for your operating system, then come back here.
You will also likely want to create a fork of this repository.
What is a “fork”?
A fork is your own personal copy of a repository, where you can test out different changes before making a “pull request” (more on pull requests later)
Further reading: GitHub - Fork A Repository
git clone https://github.com/codeday/docs
cd docs
bundle install
bundle exec jekyll serve
The site will be available at http://localhost:4000/, and live-update as you make changes.
Modifying an existing page
When you want to make a change to an existing page, the first thing you’ll need to do is find the file corresponding to the page. The easiest way to do this is scroll all the way to the bottom, and click the “Edit this page on GitHub” link.
You’ll notice right away the file isn’t quite in plain English. This is because pages are written in Markdown, a rather common format for storing text with formatting.
There are several “flavors” of markdown, the one used by these docs is called kramdown (you don’t need to know this, but just in case you want to learn more)
Common Markdown Syntax
# Headings
## And Sub-Headings
### (this keeps going)
You can write in **bold** and _italics_, too!
> this is a quote
You’ve probably used markdown before without even realizing it! Lots of social media websites (like Reddit and Discord) use markdown-style formatting.
You can see all the formatting options supported by Just the Docs here
Helpful Syntax
There are a few extra features you can use, thanks to Just the Docs.
Callouts
Callouts look like this
We support the following options for callouts:
{: .note }
> This is a note.
{: .important }
> This is important.
{: .warning }
> This is a warning.
{: .new }
> This marks something new.
You can also add custom titles:
{: .note-title }
> **Custom Title**
>
> Callout body text here.
Images
Place images in a subdirectory next to the page that uses them, or in a shared images/ folder within the section. Reference them with relative paths:
Table of Contents
You can autogenerate a table of contents (like the one at the top of this page) with the following snippet:
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
This is autogenerated based on the headings in the current document. Sometimes you want to exclude a heading from being included, which you can do by adding {: .no_toc} to the line immediately after the heading.
Ancestry
Just the Docs allows us to set “parent” pages, which helps to structure the sidebar. You need to set this manually, in the files’ frontmatter. For example, OS Project Contribution Guide is a child of CodeDay Labs - you can see this in the sidebar and in the frontmatter:
---
parent: CodeDay Labs
---
# OS Project Contribution Guide
If the page title of the parent is not unique, you will need to disambiguate using the grand_parent property. You can read more on that here.
You can also set the ordering among siblings, using the nav_order property. Lower numbers appear first.
Just the Docs will automatically create a table of contents listing child pages. You can disable this with has_toc: false in the frontmatter.
Naming Conventions and File Structure
Files must be in all lowercase, with hyphens (-) instead of spaces. This is called “Kebab Case” and looks-like-this. Filenames should ideally be a short “slug” that concisely summarizes the title. If you need help
The title of the page should (generally) be in “Title Case” and accurately represent the contents of the page. It’s okay to make exceptions to this rule for stylistic choice, such as “What do I do if I have a scheduling conflict?”
Making Your Pull Request
Once you’ve made changes to your fork, you can create a Pull Request in https://github.com/codeday/docs, and we’ll review it. When applicable, please share your reasoning - this helps us best understand your changes and keep it in mind when writing future documentation! It’s really easy for experts to write bad docs so it’s only with your help we can have the best documentation possible. ♥
What is a Pull Request?
Pull Requests (PRs) are a GitHub feature allowing you to suggest changes in a repository you don’t have write access to. You can read more about them here: GitHub - Creating a Pull Request
Pull requests need to be approved by at least one CodeDay Employee before they can get merged. Even if you aren’t an employee, you are encouraged to participate in reviewing and discussing pull requests!
If you are a CodeDay employee, you can’t sign off on your own pull request. You aren’t above the law!
Getting Help
If you need help with any of this, feel free to talk to anyone on the CodeDay Team. We’re always happy to help! You can also open pull requests as a draft if you want feedback on a change, or want confirmation you’re on the right track.