{"id":50371534,"url":"https://github.com/string-os/astro-sfmd","last_synced_at":"2026-05-30T07:03:54.827Z","repository":{"id":352522248,"uuid":"1215449337","full_name":"string-os/astro-sfmd","owner":"string-os","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-07T03:44:04.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T05:35:40.591Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/string-os.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T23:25:51.000Z","updated_at":"2026-05-07T03:44:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/string-os/astro-sfmd","commit_stats":null,"previous_names":["string-os/astro-sfmd"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/string-os/astro-sfmd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fastro-sfmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fastro-sfmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fastro-sfmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fastro-sfmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/string-os","download_url":"https://codeload.github.com/string-os/astro-sfmd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fastro-sfmd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33682998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-30T07:03:54.054Z","updated_at":"2026-05-30T07:03:54.817Z","avatar_url":"https://github.com/string-os.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @string-os/astro-sfmd\n\nBuild SFMD-native sites with Astro. Every page ships in two formats from the same source: styled HTML for browsers, raw markdown for AI agents — at predictable parallel URLs.\n\n```\n/start/quickstart/    → HTML  (humans)\n/start/quickstart.md  → raw   (AI agents)\n```\n\nTwo ways to use it.\n\n## A. Add to an existing Astro site (Starlight, vanilla, anything)\n\nThis is the lightweight path: keep your existing site (e.g. Starlight) and bolt SFMD's dual-output behavior on top.\n\n```bash\nnpm install @string-os/astro-sfmd\n```\n\n```js\n// astro.config.mjs\nimport { defineConfig } from 'astro/config';\nimport starlight from '@astrojs/starlight';\nimport sfmd from '@string-os/astro-sfmd/integration';\n\nexport default defineConfig({\n  integrations: [\n    starlight({ title: 'My Docs' /* ... */ }),\n    sfmd({ contentDir: 'src/content/docs' }),\n  ],\n});\n```\n\nWhat the integration adds:\n\n1. **Remark plugin** that strips `.md` from local link URLs in the HTML output, so humans land on `/start/quickstart/` instead of being served the raw markdown.\n2. **Post-build mirror** that copies your `.md` source tree into `dist/` so each page is also reachable as `/start/quickstart.md`. The mirrored files keep their `.md` links intact, so agent-driven traversal chains (raw → raw) still work.\n\nOptions:\n\n| Option | Default | Use |\n|---|---|---|\n| `contentDir` | (required) | Path to source `.md` files relative to project root |\n| `stripMdLinksInHtml` | `true` | Set `false` to leave `.md` in HTML link URLs |\n| `mirror` | `true` | Set `false` to skip the source-mirror (e.g. SSR) |\n\n## B. Build a fully custom SFMD site (no Starlight)\n\nThis path is for sites where you want astro-sfmd to do the rendering itself — minimal layout, your own styling, content in `content/*.md`.\n\n```bash\nmkdir my-site \u0026\u0026 cd my-site\nnpm init -y\nnpm install astro marked @string-os/astro-sfmd\n```\n\nCreate `content/index.md`:\n\n```markdown\n---\ntitle: My Site\n---\n\n# My Site\n\nWelcome. This page is readable by humans and AI agents.\n```\n\nCreate `src/pages/[...slug].astro`:\n\n```astro\n---\nimport Base from '@string-os/astro-sfmd/layouts/Base.astro';\nimport { listContentFiles, parseSfmdFile } from '@string-os/astro-sfmd';\n\nexport function getStaticPaths() {\n  return listContentFiles().map(({ filePath, slug }) =\u003e ({\n    params: { slug: slug || undefined },\n    props: { page: parseSfmdFile(filePath) },\n  }));\n}\n\nconst { page } = Astro.props;\n---\n\n\u003cBase title={page.title} nav={page.nav}\u003e\n  \u003cFragment set:html={page.htmlBody} /\u003e\n\u003c/Base\u003e\n```\n\nAdd to `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"astro dev\",\n    \"build\": \"astro build \u0026\u0026 node node_modules/@string-os/astro-sfmd/scripts/copy-sfmd.mjs\"\n  }\n}\n```\n\n```bash\nnpm run build\n```\n\nOutput:\n\n```\ndist/\n├── index.html    ← browser\n└── index.md      ← agent\n```\n\n## Deployment\n\n**Vercel / Cloudflare / static hosts** — both URL forms (`/path/` and `/path.md`) are served as static files. `.md` is auto-detected as `text/markdown`.\n\n**With Accept-header negotiation** (optional, SSR setups) — add the middleware:\n\n```js\n// src/middleware.ts\nexport { onRequest } from '@string-os/astro-sfmd/middleware';\n```\n\nThis serves the `.md` source when a request includes `Accept: text/markdown`, even at the bare `/path` URL. Useful when you don't want to teach agents the `.md` suffix convention.\n\n## What it does (full feature list)\n\n- **Source mirror** — copies `*.md` from your content directory into the build output preserving paths.\n- **HTML link rewriting** — strips `.md` from local link URLs in HTML so humans get pretty URLs while raw `.md` files keep traversable links.\n- **SFMD parser** (option B only) — reads SFMD, strips directives (`[!nav:]`, `[!include:]`, action blocks, block markers), resolves shortcuts (`[@id Label](url)` → `[Label](url)`), and renders HTML.\n- **Auto-built nav** (option B only) — `[!nav:name](path)` in your markdown becomes a sidebar.\n- **Optional middleware** — Accept-header content negotiation.\n- **Optional blog index generator** — `copy-sfmd.mjs` script also auto-generates an index `.md` for any `blog/` directory containing posts.\n\n## Choosing a path\n\n- **Use Starlight + integration (option A)** if you want polished docs UI (search, dark mode, sidebars, breadcrumbs) and just need to add agent-readable `.md` URLs.\n- **Use astro-sfmd standalone (option B)** if you want a minimal SFMD-native site without Starlight's surface, and direct control over rendering.\n\nBoth paths produce the same dual-output URL convention.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstring-os%2Fastro-sfmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstring-os%2Fastro-sfmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstring-os%2Fastro-sfmd/lists"}