All documents need to have something called YAML front matter. This is a section at the beginning of your document which starte with three dashes and ends with three dashes. In between these dashes you can specify the layout template you wish to use as well as the page title. The YAML is processed by a Jekyll engine by github. Here is an example:
--- layout: default title: How to add documentation to the docs folder ---
Add the document to the /docs folder in either HTML or Markdown (md) format. Note that HTML documents should not contain the HTML, Header, or Body tags since the documents contents will ultimately be inserted in a template which already contains these items.
In the _data folder you will find the nav.yml file. Update this file to add a link to your file.
If you are making significant changes to files in the docs/ folder you will need to verify your changes before submitting a pull request. Here’s one way to do this on Windows using the GitHub Ddesktop application.
Download and Install GitHub Desktop from here: https://desktop.github.com/
To install Jekyll bundle will rad the contents of the Gemfile in the docs directory.
From GitHub Desktop launch GitShell
Change directories
> cd docs
> bundle install
From https://github.com/chipKIT32/chipKIT-core click Fork
Then click on the user you want to Fork the repo too
From your repository page click the Settings tab
Scroll down and ensure master branch /docs folder is selected then hit save
Click on Branch:master, type in a new branch name, and then click Create branch.
Click Clone or download and select Open in Desktop
From GitShell ensure you are still in the docs folder.
Now you can start the jekyll local server
> bundle exec jekyll serve
Windows PowerShell
Copyright (C) 2016 Microsoft Corporation. All rights reserved.
~\temp\folder\chipKIT-core\docs [your-docs-branch ≡ +0 ~1 -0 !]> bundle exec jekyll serve
Configuration file: none
Configuration file: none
Source: C:/Users/boss/temp/folder/chipKIT-core/docs
Destination: C:/Users/boss/temp/folder/hipKIT-core/docs/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.52 seconds.
Please add the following to your Gemfile to avoid polling for changes:
gem 'wdm', '>= 0.1.0' if Gem.win_platform?
Auto-regeneration: enabled for 'C:/Users/boss/temp/folder/chipKIT-core/docs'
Configuration file: none
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.
From your favorite browser navigate to http://127.0.0.1:4000/
In GitHub Desktop ensure your branch is selected.
Now that you have jekyll serving your local files and your desired branch is active you can make edits to your local docments in the /docs folder or add new documents using your favorite text editor. When you save them GitHub desktop will automatically detect the changes.
At this point you will be able to refresh your browser and see the changes you have made. Note that you’ll need to navigate to the URL of the file you are creating or modifying.
When you are happy with your changes go ahead and commit them and document your progress. This only commits to your personal github repo and does not overwrite the master chipKIT-core repo. That comes next!