New contributor? Start with the Contributor Workflow for setup instructions and daily git commands.
| Site | URL |
|---|---|
| Production | https://cdcgov.github.io/NEDSS-SystemAdminGuide/ |
| Stakeholder preview | https://jburgh.github.io/CDCgov-NEDSS-SystemAdminGuide-preview/ (temporary — pending CDCgov org transfer) |
| 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 |
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.
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 for Jekyll):
- Mac:
brew install ruby(requires Homebrew) - Windows: use RubyInstaller
Install Jekyll and Bundler:
gem install bundler jekyllRun the local server:
bundle install
bundle exec jekyll servePreview at http://localhost:4000. The built site is stored in _site/.