feat: migrate to MkDocs Material - #3
Merged
BrewertonSantos merged 1 commit intoMar 29, 2026
Merged
Conversation
Copy link
Copy Markdown
There was a problem hiding this comment.
Pull request overview
Migrates the site from Jekyll/Just the Docs to MkDocs Material, moving content under docs/, applying a GitHub-dark visual theme, and updating CI/deploy pipelines to build and publish MkDocs output while aiming to maintain a strict on-page CSP.
Changes:
- Replace Jekyll configuration/theme with MkDocs Material (mkdocs.yml, requirements.txt) and a custom theme/CSP override.
- Move/convert pages into the MkDocs docs/ tree and update navigation and internal links.
- Update GitHub Actions CI/deploy workflows to use Python + mkdocs build --strict and publish the site/ directory.
Reviewed changes
Copilot reviewed 21 out of 25 changed files in this pull request and generated 1 comment.
Show a summary per file| File | Description |
|---|---|
| requirements.txt | Adds MkDocs Material dependency for Python-based builds. |
| mkdocs.yml | Defines MkDocs Material theme, nav, extensions, and custom CSS. |
| overrides/main.html | Injects CSP/referrer/etc. meta tags via Material template override. |
| .github/workflows/ci.yml | Switches CI from Ruby/Jekyll to Python/MkDocs strict builds. |
| .github/workflows/deploy.yml | Switches deploy build to MkDocs and uploads site/ artifact. |
| docs/index.md | New MkDocs home page content and updated internal linking. |
| docs/about.md | Updates About page formatting/content for MkDocs. |
| docs/projects/index.md | New Projects index page in MkDocs structure. |
| docs/projects/assets-and-map-editor.md | Converts project page to MkDocs Material components (cards/tabs/admonitions/buttons). |
| docs/guides/index.md | New Guides index page in MkDocs structure. |
| docs/guides/adding-pages.md | New contribution guide for MkDocs workflow and Markdown features. |
| docs/guides/security.md | Updates security guide to reflect MkDocs CSP approach and formatting. |
| docs/assets/css/github-dark.css | Adds GitHub-dark theme styling overrides for Material. |
| docs/assets/images/logo.svg | Adds new logo asset for Material theme. |
| docs/assets/images/favicon.svg | Adds new favicon asset for Material theme. |
| index.md | Removes old Jekyll home page (migrated to docs/index.md). |
| projects/index.md | Removes old Jekyll Projects index (migrated to docs/projects/index.md). |
| guides/index.md | Removes old Jekyll Guides index (migrated to docs/guides/index.md). |
| guides/adding-pages.md | Removes old Jekyll guide (replaced by docs/guides/adding-pages.md). |
| assets/css/custom.css | Removes Just the Docs custom CSS (replaced by MkDocs CSS). |
| _includes/head_custom.html | Removes Jekyll head include (replaced by MkDocs override). |
| _sass/color_schemes/disttopic-dark.scss | Removes Just the Docs color scheme SCSS. |
| _config.yml | Removes Jekyll site configuration. |
| Gemfile | Removes Ruby/Jekyll dependencies. |
| Gemfile.lock | Removes Ruby lockfile no longer used. |
docs/guides/security.md:23
- The table describes clickjacking/MIME protections as X-Frame-Options/X-Content-Type-Options headers, but in this PR they’re implemented as <meta http-equiv=...> tags (which browsers generally don’t enforce for these headers). To keep the security guide accurate, either remove/soften these claims or explicitly state which protections are enforced via CSP meta vs which require real HTTP response headers.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Sorry, something went wrong.
Comment thread
overrides/main.html
Comment on lines
+22
to
+34
| <!-- Security: Prevent clickjacking --> | ||
| <meta http-equiv="X-Frame-Options" content="DENY"> | ||
|
|
||
| <!-- Security: Prevent MIME type sniffing --> | ||
| <meta http-equiv="X-Content-Type-Options" content="nosniff"> | ||
|
|
||
| <!-- Security: Referrer policy --> | ||
| <meta name="referrer" content="strict-origin-when-cross-origin"> | ||
|
|
||
| <!-- Security: Permissions policy --> | ||
| <meta http-equiv="Permissions-Policy" | ||
| content="camera=(), microphone=(), geolocation=(), payment=(), usb=(), magnetometer=(), gyroscope=(), accelerometer=()"> | ||
|
|
Copilot
AI
Mar 29, 2026
Copy link
There was a problem hiding this comment.
These directives are response headers, but X-Frame-Options, X-Content-Type-Options, and Permissions-Policy are not reliably/enforced when set via <meta http-equiv=...> (many browsers ignore them). Since GitHub Pages doesn’t let you emit arbitrary HTTP headers, consider removing these meta tags (to avoid a false sense of protection) and rely on the CSP frame-ancestors 'none' + <meta name="referrer">, or document that only CSP/referrer are actually enforced.
Suggested change
| <!-- Security: Prevent clickjacking --> | |
| <meta http-equiv="X-Frame-Options" content="DENY"> | |
| <!-- Security: Prevent MIME type sniffing --> | |
| <meta http-equiv="X-Content-Type-Options" content="nosniff"> | |
| <!-- Security: Referrer policy --> | |
| <meta name="referrer" content="strict-origin-when-cross-origin"> | |
| <!-- Security: Permissions policy --> | |
| <meta http-equiv="Permissions-Policy" | |
| content="camera=(), microphone=(), geolocation=(), payment=(), usb=(), magnetometer=(), gyroscope=(), accelerometer=()"> | |
| <!-- Security: Referrer policy --> | |
| <meta name="referrer" content="strict-origin-when-cross-origin"> |
Sorry, something went wrong.
Copilot uses AI. Check for mistakes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sorry, something went wrong.
Uh oh!
There was an error while loading. Please reload this page.