refactor: move docs to the main repo; make cot-site a lib by m4tx · Pull Request #77 · cot-rs/cot-site

m4tx · 2026-03-04T19:32:26Z

No description provided.

This changes the character of the repository. Now it's no longer an actual website, but rather an engine to build the website. It requires providing the documentation for the "master" version of the guide, while the older versions are stored directly on this repository. Eventually, newer versions will use git submodules to pull the docs from the `cot` repository as well. This is a part of the initiative to bring better documentation to Cot: cot-rs/cot#471

Copilot

Pull request overview

This PR refactors cot-site into more of a reusable “website engine” by moving guide/markdown content out of src/md-pages into a docs/ tree, adding a proc-macro path scheme that can load markdown from an external repo layout, and precomputing/caching parsed pages + the Pagefind search index during app initialization.

Changes:

Move versioned guide markdown from src/md-pages/** into docs/** and adjust the markdown proc-macro to read from those paths (plus a new external_md_page macro).
Refactor guide parsing so pages are pre-parsed once and passed around via Arc<ParsedPages>.
Change search index initialization to happen in CotSiteApp::init() (global OnceCell), removing lazy generation from the FromRequestHead extractor.

Reviewed changes

Copilot reviewed 29 out of 81 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`src/search.rs`	Search index generation now consumes pre-parsed pages and expects global initialization via `SEARCH_INDEX`.
`src/lib.rs`	Converts app into a reusable engine (`CotSiteApp` with pre-parsed pages), initializes Pagefind index in `init()`, and exposes error handler as a function.
`src/guides.rs`	Refactors guide parsing to build a per-version map once (`ParsedPages`) and removes per-request parsing.
`README.md`	Renames project to “Cot Website Engine” and clarifies guide content lives in the cot repo.
`Cargo.toml`	Adds licensing, new deps (async-trait/rustversion), and switches `cot` to a git rev.
`.gitignore`	Adds `Cargo.lock` to ignored entries.
`Dockerfile`	Removed.
`compose.yml`	Removed.
`compose.dev.yml`	Removed.
`bacon.toml`	Removed.
`.github/workflows/docker.yml`	Removed Docker image CI workflow.
`.dockerignore`	Removed.
`cot-site-macros/src/md_pages.rs`	Changes markdown file resolution to arbitrary paths; adds input type for external markdown.
`cot-site-macros/src/lib.rs`	Adds `external_md_page` proc macro and updates `md_page` to read from `docs/{prefix}`.
`cot-site-macros/Cargo.toml`	Adds license; adds `rustversion` build-dependency.
`cot-site-macros/build.rs`	Adds nightly detection + cfg emission for tracked paths (but has a directive formatting bug).
`cot-site-common/Cargo.toml`	Adds license metadata.
`src/md-pages/v0.5/upgrade-guide.md`	Removed (moved to `docs/v0.5/upgrade-guide.md`).
`src/md-pages/v0.5/testing.md`	Removed (moved to `docs/v0.5/testing.md`).
`src/md-pages/v0.5/static-files.md`	Removed (moved to `docs/v0.5/static-files.md`).
`src/md-pages/v0.5/sending-emails.md`	Removed (moved to `docs/v0.5/sending-emails.md`).
`src/md-pages/v0.5/openapi.md`	Removed (moved to `docs/v0.5/openapi.md`).
`src/md-pages/v0.5/framework-comparison.md`	Removed (moved to `docs/v0.5/framework-comparison.md`).
`src/md-pages/v0.5/forms.md`	Removed (moved to `docs/v0.5/forms.md`).
`src/md-pages/v0.5/error-pages.md`	Removed (moved to `docs/v0.5/error-pages.md`).
`src/md-pages/v0.5/db-models.md`	Removed (moved to `docs/v0.5/db-models.md`).
`src/md-pages/v0.5/caching.md`	Removed (moved to `docs/v0.5/caching.md`).
`src/md-pages/v0.5/admin-panel.md`	Removed (moved to `docs/v0.5/admin-panel.md`).
`src/md-pages/master/introduction.md`	Removed (master docs now expected externally / via new macro).
`docs/v0.5/upgrade-guide.md`	Added versioned guide content under `docs/`.
`docs/v0.5/testing.md`	Added versioned guide content under `docs/`.
`docs/v0.5/static-files.md`	Added versioned guide content under `docs/`.
`docs/v0.5/sending-emails.md`	Added versioned guide content under `docs/`.
`docs/v0.5/framework-comparison.md`	Added versioned guide content under `docs/`.
`docs/v0.5/forms.md`	Added versioned guide content under `docs/`.
`docs/v0.5/error-pages.md`	Added versioned guide content under `docs/`.
`docs/v0.5/caching.md`	Added versioned guide content under `docs/`.
`docs/v0.5/admin-panel.md`	Added versioned guide content under `docs/`.
`docs/v0.4/upgrade-guide.md`	Added versioned guide content under `docs/`.
`docs/v0.4/testing.md`	Added versioned guide content under `docs/`.
`docs/v0.4/static-files.md`	Added versioned guide content under `docs/`.
`docs/v0.4/forms.md`	Added versioned guide content under `docs/`.
`docs/v0.4/error-pages.md`	Added versioned guide content under `docs/`.
`docs/v0.4/db-models.md`	Added versioned guide content under `docs/`.
`docs/v0.4/admin-panel.md`	Added versioned guide content under `docs/`.
`docs/v0.3/testing.md`	Added versioned guide content under `docs/`.
`docs/v0.3/static-files.md`	Added versioned guide content under `docs/`.
`docs/v0.3/forms.md`	Added versioned guide content under `docs/`.
`docs/v0.3/error-pages.md`	Added versioned guide content under `docs/`.
`docs/v0.3/db-models.md`	Added versioned guide content under `docs/`.
`docs/v0.3/admin-panel.md`	Added versioned guide content under `docs/`.
`docs/v0.2/testing.md`	Added versioned guide content under `docs/`.
`docs/v0.2/static-files.md`	Added versioned guide content under `docs/`.
`docs/v0.2/forms.md`	Added versioned guide content under `docs/`.
`docs/v0.2/error-pages.md`	Added versioned guide content under `docs/`.
`docs/v0.2/db-models.md`	Added versioned guide content under `docs/`.
`docs/v0.2/admin-panel.md`	Added versioned guide content under `docs/`.
`docs/v0.1/testing.md`	Added versioned guide content under `docs/`.
`docs/v0.1/static-files.md`	Added versioned guide content under `docs/`.
`docs/v0.1/forms.md`	Added versioned guide content under `docs/`.
`docs/v0.1/error-pages.md`	Added versioned guide content under `docs/`.
`docs/v0.1/db-models.md`	Added versioned guide content under `docs/`.
`docs/v0.1/admin-panel.md`	Added versioned guide content under `docs/`.
`docs/licenses.md`	Adds consolidated licenses page in `docs/`.
`docs/faq.md`	Adds FAQ page in `docs/`.

Comments suppressed due to low confidence (1)

src/lib.rs:323

context.router() is assigned to router but never used. If this call is only meant for side effects, rename the binding to _router (or add a clarifying comment); otherwise remove it to avoid dead code and confusion.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

seqre · 2026-03-15T12:49:51Z

cot-site-macros/build.rs

 fn main() {
    build_syntax_highlighting_defs();

+    println!("cargo::rustc-check-cfg=cfg(cot_use_nightly)");


I think that's a valid suggestion

It's not, it's a hallucination: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-check-cfg

It seems like both work; if anything, I can change everything to double colons so that it's consistent with the official docs.

EDIT: "both work" since 1.77: "MSRV: 1.77 is required for cargo::KEY=VALUE syntax. To support older versions, use the cargo:KEY=VALUE syntax."

src/search.rs

seqre

Is this only going to be used as a git repository or did you forget to add release-plz here?

seqre · 2026-03-15T12:49:51Z

cot-site-macros/build.rs

 fn main() {
    build_syntax_highlighting_defs();

+    println!("cargo::rustc-check-cfg=cfg(cot_use_nightly)");


I think that's a valid suggestion

m4tx · 2026-03-15T12:54:19Z

Is this only going to be used as a git repository or did you forget to add release-plz here?

I don't think there's a reason to publish this on crates.io. It's only an internal thing anyway, and it's easier to work on changes here when it's not being published.

ElijahAhianyo · 2026-03-16T17:53:25Z

src/lib.rs

+}
+
+impl CotSiteApp {
+    pub fn new(master_pages: Vec<(&'static str, Vec<MdPage>)>) -> Self {


We should add some documentation here indicating that the method takes in the name of a section and the list of pages in that section

Fair point!

m4tx force-pushed the move-master-to-cot branch 2 times, most recently from 65bd9ee to d8c3904 Compare March 15, 2026 11:04

m4tx mentioned this pull request Mar 15, 2026

refactor: add docs-site with locally-sourced docs cot-rs/cot#510

Merged

m4tx force-pushed the move-master-to-cot branch 4 times, most recently from 563c754 to 3edd3d6 Compare March 15, 2026 11:37

m4tx force-pushed the move-master-to-cot branch from 3edd3d6 to 17d37ae Compare March 15, 2026 11:41

m4tx marked this pull request as ready for review March 15, 2026 12:13

m4tx requested review from ElijahAhianyo, Copilot and seqre March 15, 2026 12:13

Copilot started reviewing on behalf of m4tx March 15, 2026 12:14 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

seqre reviewed Mar 15, 2026

View reviewed changes

fixes

0e1fe83

m4tx requested a review from seqre March 15, 2026 13:03

fixes

0869a5d

seqre approved these changes Mar 15, 2026

View reviewed changes

ElijahAhianyo reviewed Mar 16, 2026

View reviewed changes

address review comments

125e007

m4tx enabled auto-merge (squash) March 17, 2026 19:02

m4tx merged commit b058940 into master Mar 17, 2026
10 checks passed

m4tx deleted the move-master-to-cot branch March 17, 2026 19:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: move docs to the main repo; make cot-site a lib#77

refactor: move docs to the main repo; make cot-site a lib#77
m4tx merged 4 commits intomasterfrom
move-master-to-cot

m4tx commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

seqre Mar 15, 2026

Uh oh!

m4tx Mar 15, 2026 •

edited

Loading

Uh oh!

Uh oh!

seqre left a comment

Uh oh!

seqre Mar 15, 2026

Uh oh!

m4tx commented Mar 15, 2026

Uh oh!

ElijahAhianyo Mar 16, 2026

Uh oh!

m4tx Mar 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

m4tx commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

seqre Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

m4tx Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

seqre left a comment

Choose a reason for hiding this comment

Uh oh!

seqre Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

m4tx commented Mar 15, 2026

Uh oh!

ElijahAhianyo Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

m4tx Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

m4tx Mar 15, 2026 •

edited

Loading