jacobcsmith / sage-docs

Documentation for SAIC's Sage product. Powered by Docusaurus and published to GitHub Pages

docusaurus-example

Example implementation of a documentation site powered by Docusaurus and published to GitHub Pages

See the webapp directory for the Docusaurus code

Prerequisites

• go-task
• pre-commit
• Current version of Node/NPM

Getting Started

1. Fork/Import this repository
2. (SAICers) Change LICENSE to whichever license that needs to be applied here
   1. If you are providing documentation for something that is being published as open source, the license of this project should match the license of the software
   2. If you are publishing the documentation of a proprietary/commercial product, use Createive Commons Attribution NonCommercial ShareAlike (CC-NC-SA)
3. Edit ./webapp/docusaurus.config.js
   1. title: - Title of your site
   2. tagline: - Tagline of your site
   3. url: - URL of the base website (SAICers: You shouldn't need to change this)
   4. baseUrl: - Base path that your site lives on. Should be the same as the github repo name
   5. organizationName: - GitHub org name (SAICers: You shouldn't need to change this)
   6. projectName: - Name of the GitHub repo
   7. other - make whatever other changes you need to customize your site
4. Get the project wired up with a compliant CI/CD pipeline. SAIC uses CodeFresh for this. Please contact the admins.

Usage

# Validate project
task validate

# Run tests
task test

# Run security scans (there aren't any yet)
task secure

# Run the site locally, have it watch for changes and automatically rebuild
task start

# Build the Docusaurus static content
task build

# Deliver/Deploy the specified branch to GitHub Pages
GIT_USER="bobbytables" \
GIT_PASS="abc123abc123abc123abc123abc123abc123" \
DEPLOYMENT_BRANCH="gh-pages" \
CURRENT_BRANCH="main" \
GIT_CONFIG_USR="Robert Tables" \
GIT_CONFIG_EMAIL="[e-mail]" \
task deliver

See more Docusaurus-centric instructions in ./webapp/README.md or at https://v2.docusaurus.io/