This is an early prototype of what The Carpentries Handbook might look like. Everything is a work in progress and does not currently contain any actual Carpentries documentation. The site can be previewed at this Netlify link.
/build/
Used to build local website. In .gitignore
so this will not show up in the repo. Do not edit these files./source/
Contains all the files needed to build the site. Includes:
rst
files with content for each page. This includes one folder for each area of work, plus a folder called pages
for general pages such as the style guide, glossary, and other landing pages./_includes/
- text blocks and other content to be included in other pages/_templates/
- templates for specialized content such as the table of contents in the sidebar/_static/
- contains custom css styles conf.py
- site settingsindex.rst
- sets structure for home page.gitignore
Standard gitignore fileMakefile
- includes custom Make commands and inherits general Sphinx Make commands.Content is organized in the source
directory. Edits to content should be made to these files. Do not edit files in the build
folder.
Most styling comes from the pydata_sphinx_theme
template. Custom styles are implemented in /source/_static/css
. This includes the font files for the Mulish Google font and a custom css file.
Most templates and layouts come from the pydata_sphinx_theme
template. Custom page templates are implemented in /source/_templates/
. For example, the standard theme includes Python functions to build templates for the table of contents in the sidebar and top navigation bar. Instead, we use custom and hard coded templates. These are then called in html_theme_options
in conf.py
.
The handbook is built using Sphinx and the pydata_sphinx_theme
.
make clean
Removes all files in the build
directorymake html
Builds the site and publishes html content to the build directoryconf.py
After setting the theme, the additional following changes were needed to conf.py
. Note this list does not include changes that only reflect The Carpentries identity (setting the name, social media handles, etc.). The list includes changes that affect the site functionality.
.md
to the source_suffix
list and add myst_parser
to the extensions
listhtml_static_path = ['_static']
and html_css_files = ['css/custom.css']
html_context
. This is supposed to enable the "Edit on GitHub" button, but does not work.html_context
myst_heading_anchors = 6
suppress_warnings = ['autosectionlabel.*']
This site is set up to preview all pull requests via Netlify. Note Netlify login is required to setup and manage Netlify. All PRs will offer a public Netlify preview link.