New contributor? Start with the Contributor File Map.
Production site: https://cdcgov.github.io/NEDSS-SystemAdminGuide/ Stakeholder preview site: https://cdcgov.github.io/NEDSS-SystemAdminGuide/preview/
| Action | Location |
|---|---|
| Stage content for stakeholder review | Push to preview branch — see Stakeholder Review Workflow |
| Previous release versions | Any branch named release-<version> is automatically added under PREVIOUS VERSIONS |
| Access versioned docs | Located under PREVIOUS VERSIONS section |
Use this map to find contributor guidance quickly.
| File | What it helps with |
|---|---|
| README.md | Project overview, local preview options, and site workflow context |
| CONTRIBUTING.md | Contribution standards, review expectations, CI checks, and local scripts/commands |
| workflow.md | Day-to-day git workflow, branch strategy, preview-to-production process, and required docs/revision-history.md updates before merging to main |
| styles.md | Authoring standards: front matter, headings, callouts, links, code blocks, images, tables, and Section 508 / WCAG 2.1 AA compliance record |
| File | What it helps with |
|---|---|
| code-of-conduct.md | Community behavior expectations and reporting process |
| open_practices.md | Open-source collaboration practices and participation norms |
| rules_of_behavior.md | Required behavior and participation rules for this CDC project space |
| LICENSE | Repository licensing terms and usage rights |
| CDCgov_README.md | CDC open-source project baseline notes and agency-specific repository context |
GitHub Pages hosts System Admin Guide site by serving static HTML, CSS, and JS directly from this repository (via GitHub Actions).
Just the Docs is a Jekyll-based theme optimized for documentation sites, fully-compatible with GitHub Pages—providing menus, search, collections, and theming out-of-the-box.
One GitHub Actions workflow (jekyll.yml) builds and deploys everything. It triggers on a push to main or to preview, and produces a single Pages deployment containing:
docs/built frommain, served at https://cdcgov.github.io/NEDSS-SystemAdminGuide/- Any
release-*branches built into_previous_versions/<branch>/ - The
previewbranch built intopreview/, served at https://cdcgov.github.io/NEDSS-SystemAdminGuide/preview/
A repository publishes one Pages site and each deployment replaces it whole, so the preview cannot be a separate deployment. Production content is always built from main, whichever branch triggered the run.
The review workflow uses a dual long-lived branch system: main matches production, preview feeds the staging site. See the Quick Guide table above for site URLs.
How it works:
- Authors do their work on a short-lived feature branch created from
main - When ready for review, the feature branch is merged into the long-lived
previewbranch and pushed — this triggers an automatic deploy to the preview site - Stakeholders browse the preview site and provide async feedback
- Authors iterate: update the feature branch, re-merge to
preview, repeat - Once approved, the feature branch is merged to
mainvia PR — neverpreviewdirectly tomain, aspreviewaccumulates work from multiple authors
For step-by-step git commands, see workflow.md.
Branches starting with release- are automatically built and deployed under /previous_versions/<branch>/ via GitHub Actions. See release-checklist.md.
We use GitHub-Flavored Markdown (GFM) for tables, fenced code blocks, lists, etc.
Just the Docs theme renders pages according to _config.yml, supporting navigation, collections, syntax highlighting, and more.
Page layout convention for all content pages: place brief intro text directly under the H1, then include the On this page TOC block, and start the first H2 section immediately after the TOC. See styles.md.
Which option should I use?
- Content authors (text edits, new pages): Option 1 is sufficient for most work.
- Anyone changing
_config.yml,_sass/, templates, or site structure: use Option 2 or Option 3. VS Code preview does not render theme or config changes. - Option 2 vs Option 3: same result, different tooling. Use Option 3 (Docker) if you don't want to install Ruby locally.
VS Code has a built-in markdown preview. Open any .md file and press Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows) to open a rendered preview alongside your editor. This is sufficient for most content work.
For a full rendered view of the site with navigation and theme intact, push to the preview branch instead — see Stakeholder Review Workflow.
Use this if you are modifying _config.yml, _sass/, or anything that affects site structure or appearance rather than content.
Install Ruby: (first-time setup)
- Mac:
brew install ruby(requires Homebrew) - Windows: use RubyInstaller
Install Bundler: (first-time setup)
gem install bundlerRun the local server: (first-time setup)
bundle install
bundle exec jekyll serve --livereloadRebuild the local site: (any time)
bundle exec jekyll buildNote: If you get an alert that the gems or json can't be found, do another bundle install and then try the build command again.
Preview at http://localhost:4000. The browser reloads automatically when you save a file. The built site is stored in _site/.
Use this for the same purpose as Option 2, but without installing Ruby locally. Requires Docker Desktop.
Run the local server:
docker compose upPreview at http://localhost:4000. Live reload is enabled — the browser refreshes automatically when you save a file.
First run: Docker pulls the Ruby image and installs gems, which takes a few minutes. Subsequent runs are fast because gems are cached in a Docker volume.
Stop the server: Press Ctrl+C in the terminal, then run:
docker compose down