diff --git a/docs/content/_index.md b/docs/content/_index.md index 041b6b1..debfb62 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -22,6 +22,7 @@ Ready to try it? Start with the [Getting Started](getting-started.html) guide. ## Learn More - [Getting Started](getting-started.html) — install sukr and build your first site +- [Deployment](deployment.html) — deploy your site to GitHub Pages, Netlify, or any static host - [Configuration](configuration.html) — `site.toml` reference and CLI options - [Content Organization](content-organization.html) — how directories map to site structure - [Architecture](architecture.html) — how sukr works under the hood diff --git a/docs/content/deployment.md b/docs/content/deployment.md new file mode 100644 index 0000000..e8e0c00 --- /dev/null +++ b/docs/content/deployment.md @@ -0,0 +1,75 @@ +--- +title: Deployment +description: Deploy your sukr site to any static hosting platform +weight: 1 +--- + +sukr builds your site to `public/`. This directory contains self-contained static HTML, CSS, and assets — no server-side runtime needed. Upload it anywhere that serves static files. + +## Local Preview + +Preview your site locally before deploying: + +```bash +cd public +python3 -m http.server 8000 +``` + +Open `http://localhost:8000` in your browser. + +## GitHub Pages + +1. Push your repository to GitHub +2. Build your site: `sukr` +3. Deploy the `public/` directory using one of: + - **GitHub Actions** — add a workflow that runs `sukr` and deploys `public/` to Pages + - **Manual** — push the `public/` contents to a `gh-pages` branch + +Example workflow (`.github/workflows/deploy.yml`): + +```yaml +name: Deploy +on: + push: + branches: [main] +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: cargo install --path . + - run: sukr + - uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./public +``` + +## Netlify + +1. Connect your repository in the Netlify dashboard +2. Set build command: `cargo install --path . && sukr` +3. Set publish directory: `public` + +Netlify detects changes and rebuilds automatically on push. + +## Cloudflare Pages + +1. Connect your repository in the Cloudflare Pages dashboard +2. Set build command: `cargo install --path . && sukr` +3. Set build output directory: `public` + +## Any Static Host + +For any host that serves static files (S3, DigitalOcean Spaces, a VPS): + +```bash +sukr +rsync -avz public/ user@server:/var/www/mysite/ +``` + +Or use `scp`, `aws s3 sync`, or your host's CLI tool. + +## Security Headers + +sukr outputs zero JavaScript, which means you can set a strict Content Security Policy that blocks all script execution. See [Security](security.html) for recommended CSP headers and platform-specific configuration. diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index 680401f..8db8127 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -120,6 +120,7 @@ Open `public/index.html` in your browser. You should see your "Hello, World!" pa ## Next Steps +- [Deployment](deployment.html) — put your site on the web - [Configuration](configuration.html) — customize `site.toml` options (paths, navigation, base URL) - [Content Organization](content-organization.html) — learn how directories map to site sections - [Features](features/index.html) — syntax highlighting, math, diagrams, and more diff --git a/docs/plans/documentation-overhaul.md b/docs/plans/documentation-overhaul.md index 2d8df7c..780a2f2 100644 --- a/docs/plans/documentation-overhaul.md +++ b/docs/plans/documentation-overhaul.md @@ -78,9 +78,9 @@ None. All CHALLENGE questions resolved. - [x] Add "Theming" section to `syntax-highlighting.md` (choosing/customizing themes) 3. **Phase 3: Fill Content Gaps** — cover Deploy and Customize stages of user journey - - [ ] Create `docs/content/deployment.md` (how-to: generic static host deployment + platform links) - - [ ] Update `_index.md` to cross-link to new deployment page - - [ ] Update `getting-started.md` "Next Steps" to include deployment + - [x] Create `docs/content/deployment.md` (how-to: generic static host deployment + platform links) + - [x] Update `_index.md` to cross-link to new deployment page + - [x] Update `getting-started.md` "Next Steps" to include deployment 4. **Phase 4: README + Cross-references** — README serves as focused explanation, cross-links established - [ ] Restructure `README.md` to explanation quadrant (what, why, how it compares) @@ -102,8 +102,9 @@ None. All CHALLENGE questions resolved. ## Technical Debt -| Item | Severity | Why Introduced | Follow-Up | Resolved | -| :--- | :------- | :------------- | :-------- | :------: | +| Item | Severity | Why Introduced | Follow-Up | Resolved | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------------------------ | :--------------------------------------------------------------- | :------: | +| `deployment.md` and `content-organization.md` both have weight 1 — alphabetical sort puts Content Org before Deployment in sidebar, suboptimal for user journey | Low | Changing other page weights was scope creep for Phase 3 | Adjust weights to match Install → Deploy → Organize user journey | ☐ | ## Retrospective