docs(website): serve Markdown source at .md URLs - #701
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
Greptile SummaryAdds
Confidence Score: 4/5The PR appears safe to merge, with only a non-blocking source-formatting inconsistency to address. The Markdown endpoint integration, dependency resolution, and tested static-file collision have no identified behavioral defect; the sole accepted concern is that newly added code conflicts with the repository’s required indentation and quote style. Files Needing Attention: website/astro.config.mjs, website/tests/docs-smoke.spec.ts Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart LR
Source[Starlight docs source] --> Plugin[starlight-dot-md]
Plugin --> Markdown["/docs/path.md"]
Source --> Starlight[Starlight renderer]
Starlight --> HTML["/docs/path/"]
Public["public/docs/hunk-review-skill.md"] --> Static["/docs/hunk-review-skill.md"]
Prompt To Fix All With AI### Issue 1
website/astro.config.mjs:5
**Inconsistent source formatting**
The new import and the test added in `website/tests/docs-smoke.spec.ts` use double-quoted strings and two-space indentation instead of the repository-required single quotes and four-space indentation, introducing inconsistent formatting and avoidable formatter churn.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "docs(website): serve Markdown source at ..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| import { defineConfig } from "astro/config"; | ||
| import sitemap from "@astrojs/sitemap"; | ||
| import starlight from "@astrojs/starlight"; | ||
| import starlightDotMd from "starlight-dot-md"; |
There was a problem hiding this comment.
The new import and the test added in website/tests/docs-smoke.spec.ts use double-quoted strings and two-space indentation instead of the repository-required single quotes and four-space indentation, introducing inconsistent formatting and avoidable formatter churn.
Context Used: guidelines.mdc Cursor rule (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: website/astro.config.mjs
Line: 5
Comment:
**Inconsistent source formatting**
The new import and the test added in `website/tests/docs-smoke.spec.ts` use double-quoted strings and two-space indentation instead of the repository-required single quotes and four-space indentation, introducing inconsistent formatting and avoidable formatter churn.
**Context Used:** guidelines.mdc Cursor rule ([source](https://github.com/modem-dev/modem/blob/main/.cursor/rules/guidelines.mdc))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
There was a problem hiding this comment.
Same as the reply on #700 — declining, the rule appears to come from a different repository.
guidelines.mdc is in modem-dev/modem; modem-dev/hunk has no .cursor directory and doesn't inherit it.
Formatting here is enforced by oxfmt at default settings — 2-space indent, double quotes. oxfmt --check reports both changed files already conform, and .lintstagedrc.json runs oxfmt --write pre-commit, so the "avoidable formatter churn" this flags would actually be introduced by making the suggested change, not avoided by it.
There was a problem hiding this comment.
You're right, my mistake. The guidelines.mdc rule belongs to modem-dev/modem and I incorrectly applied it here. Given that oxfmt --check confirms the current formatting is correct for this repo, the suggestion was backwards — the change I proposed would have introduced a violation, not fixed one.
I attempted to deactivate the guidelines.mdc rule for this repo but the action was blocked. You may want to remove or scope that custom instruction manually at https://app.greptile.com/review/custom-instructions to prevent it from firing on modem-dev/hunk PRs in the future.
A hunk.dev docs link pasted into an agent currently resolves to HTML that has to be converted back to Markdown, which is lossy in exactly the places that matter for a CLI tool. The llms.txt corpus added alongside this covers the "learn Hunk" case; this covers reading a single page. Add starlight-dot-md so every docs page's source is available at the same URL plus `.md` (/docs/start/install.md). Sitemap stays canonical-only, so no duplicate-content pollution, and the hand-authored skill file served from public/ is not shadowed. Known wart: docs/index.mdx serves raw MDX, so /docs.md includes its import statement and <CardGrid>/<LinkCard> tags. It is the only .mdx page, the attributes stay readable, and llms-full.txt already renders that page as plain prose. Converting it to .md would cost the card grid for humans, which is the worse trade.
7a222ba to
decfbbd
Compare
1 participant
Follows #700 (merged). Rebased onto
main, so the diff here is just the.mdendpoints.What
Adds
starlight-dot-md. Every docs page's Markdown source is now served at the same URL plus.md:29 doc pages, one line of config.
Why this and not just llms.txt
They cover different access patterns. The corpus files are for learning Hunk — an agent pulls ~32k tokens once and knows the tool. This is for reading one page when an agent already knows Hunk and someone pastes it a link.
The concrete win is fidelity, not discovery. HTML→Markdown conversion is lossy in exactly the places that hurt a CLI tool, and #700 demonstrated it: Starlight's heading anchors serialized into 170
Section titled "…"](#…)artifacts that needed a CSS selector to strip. Source served as source has none of that.Worth being clear on the limit, since it shapes how much this is worth: agents generally don't probe for
.md. I don't — I fetch the URL I'm given. This pays off when the pattern is advertised (an AGENTS.md rule, or a link that already ends in.md), not merely because the route exists.Reviewer notes
Verified no collateral damage:
.md. No duplicate-content pollution.public/docs/hunk-review-skill.mdis not shadowed — the hand-authored skill file still serves intact. Asserted in the test, since a silent shadow would be easy to miss.website:links,astro check,oxlintall clean.Known wart:
docs/index.mdxserves raw MDX, so/docs.mdincludes itsimportstatement and 8<CardGrid>/<LinkCard>tags rather than prose. It's the only.mdxpage in the docs; the card attributes stay readable enough for an LLM to parse the nav intent; andllms-full.txtalready renders that page as clean prose because it converts from rendered HTML. Converting the page to.mdwould cost the card grid for human readers — the worse trade, so I left it.Minor: frontmatter is Starlight's resolved schema (
template: doc,pagefind: true, …) rather than the author's source frontmatter. ~8 lines per page, no config option to trim it, not worth caring about.Testing
Full website suite 38/38 passing. New test asserts the
.mdroute returns raw source (not HTML with a.mdsuffix), preserves fenced code blocks, that the HTML companion still renders, and that the skill file isn't shadowed.Empty changeset — website-only, no effect on the published
hunkdiffpackage.🤖 Generated with Claude Code