New contributor? Start with the Contributor File Map.
Production site: https://cdcgov.github.io/NEDSS-SystemAdminGuide/ Stakeholder preview site: https://jburgh.github.io/CDCgov-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 |
| Publish approved content without showing it in nav yet | _guide_preview/*.md — see Hidden Draft Pages |
Use this map to find contributor guidance quickly.
| File | What it helps with |
|---|---|
| README.md | Project overview, local preview options, and site workflow context |
| WORKFLOW.md | Day-to-day git workflow, branch strategy, and preview-to-production process |
| CONTRIBUTING.md | Contribution standards, review expectations, CI checks, and local scripts/commands |
| File | What it helps with |
|---|---|
| STYLES.md | Authoring style rules for headings, callouts, links, code blocks, images, and tables |
| FRONT-MATTER.md | Required front matter fields and nav metadata rules for pages |
| ACCESSIBILITY.md | Accessibility requirements for alt text, heading order, links, and tables |
| 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.
Two GitHub Actions workflows handle builds and deploys:
Production (jekyll.yml) — triggers on push to main:
- Builds
docs/and_guide_preview/into_site/ - Discovers and builds any
release-*branches into_previous_versions/<branch>/ - Deploys to GitHub Pages at https://cdcgov.github.io/NEDSS-SystemAdminGuide/
Preview (jekyll-preview.yml) — triggers on push to preview:
- Builds the site with the preview baseurl
- Deploys to the staging repo at https://jburgh.github.io/CDCgov-NEDSS-SystemAdminGuide-preview/
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.
Hidden Draft Pages
Edge case — not the standard review workflow. Use this only when content is already approved and merged to
main, but you want to publish it without it appearing in navigation yet — for example, while finishing out the rest of a section. For pre-approval stakeholder review, use the Stakeholder Review Workflow instead.
Drop Markdown files into the _guide_preview/ directory to serve content on the production site that is:
- Rendered and available, but hidden from navigation and search
- Accessible only via direct URL (e.g.
/guide_preview/my-file/)
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 (required):
- Mac:
brew install ruby(requires Homebrew) - Windows: use RubyInstaller
Install Bundler:
gem install bundlerRun the local server:
bundle install
bundle exec jekyll serve --livereloadPreview 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