The jekyll static site generator can be installed on Linux, MacOS and Windows. To install a local version of jekyll follow the instructions for your respective operating system here.
Clone the repository
Once jekyll has been installed,
the repository. Navigate to the cloned repository and run
bundle install to
install the specific ruby gems necessary to run jekyll and serve the site.
Once installation is complete, it is a good idea to run
(it is a good idea to
bundle update every so often to stay up to date).
Serve a local version of the site
Now that the both jekyll and the repository are installed on your local
machine, you can run the static site generator by navigating to your local site
directory within a terminal and running
bundle exec jekyll serve. Wait for a
minute while the site generates, and then in your browser navigate to the
server address that has been output in your terminal, i.e.
http://127.0.0.1:4000. Changes you make to any file in
the directory will be detected by jekyll, regenerating the site to reflect the
Alternatively, you can run
bundle exec jekyll serve --incremental to initiate
the local server. This command will reduce the amount of time it takes for the
site to regenerate if you anticipate making many changes in quick succession.
Create a new page in
In the desired folder beneath
_pages, create a new text
Editing a page locally
We recommend using a text editor to add content and make changes to a page when working locally. A text editor makes navigating between files, searching for text within your page, and making multiple edits more efficient and provides a more user-friendly interface.
From here, the front matter and content of the new page can be populated with a text editor of your choosing.
Images and other media should be stored in
Regularly save your progress with commits. The process of commiting your changes pushes your edits to the main branch of the repository hosted on
GitHub. The process of commiting is described below.
Create an extension
You can add your scripts into
_includes/extensions, and then the user can enable your extension by adding the extension name to
extensions in the Front Matter of their markdown file.
For example, you can find two example extensions
imjoy in the
And in the begining of any page, you can enable them by:
--- title: My Awesome Page extensions: ["imjoy", "mathjax"] ---
Pushing, pulling, and commiting with Git
Once you are ready to publish your your new page you will need to add, commit, and push your changes to the repository. These steps should looks something like:
git add path/to/your-page-name.mdThis step stages your changes to be commited.
git commit path/to/your-page-name.mdNote: you will not be prompted to enter a commit message. Our usership uses imperative tense, i.e. “Add new page xzy”
git pushYour new page or edits will not be pushed to the main branch of the repository.
This guide provides further
explanations on the above steps, as well as how to keep your local repository
up-to-date with the remote with