Skip to content

[documentation / submitty.org] Containerize documentation site#748

Open
Pavan-Srivathsa wants to merge 1 commit intoSubmitty:mainfrom
Pavan-Srivathsa:containerize-docs-site
Open

[documentation / submitty.org] Containerize documentation site#748
Pavan-Srivathsa wants to merge 1 commit intoSubmitty:mainfrom
Pavan-Srivathsa:containerize-docs-site

Conversation

@Pavan-Srivathsa
Copy link
Copy Markdown

Why is this Change Important & Necessary?

Building the documentation site requires installing Ruby and managing
gem dependencies locally, which is painful for infrequent contributors
(as noted in Submitty/Submitty#12685). Ruby version conflicts and native
extension compilation failures are common pain points.

What is the New Behavior?

Contributors can now run the documentation site with a single command:
docker compose up

No Ruby, Bundler, or gem installation required. The setup includes:

  • Volume mounts for live reload (edits show instantly)
  • A named volume for gem caching (fast restarts)
  • Force polling for cross-platform file change detection
  • LiveReload for automatic browser refresh

What steps should a reviewer take to test?

  1. Install Docker if not already installed
  2. Clone this branch
  3. Run docker compose up --build
  4. Verify the site loads at http://localhost:4000
  5. Edit any markdown file in _docs/ and confirm the browser refreshes
  6. Run docker compose down && docker compose up to confirm fast restart
  7. Optionally test the link checker:
    docker compose exec docs bundle exec jekyll build
    docker compose exec docs bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external

Automated Testing & Documentation

README.md updated with Docker setup instructions. Existing Ruby/Bundler
instructions preserved. No automated test changes needed.

Other information

Not a breaking change. No migrations required.
Resolves Submitty/Submitty#12685

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Seeking Reviewer

Development

Successfully merging this pull request may close these issues.

Containerize documentation site

1 participant