markdown export from URL

[emma-squared]

Summary

This PR introduces a new feature that allows AI agents and CLI tools to access goose documentation pages as markdown by appending .md to the URL of any documentation page.

Key Features

Markdown Export Functionality

1. Markdown Export Plugin:

   • Created a custom Docusaurus plugin (markdown-export.cjs) to process source documentation files.
   • Strips YAML frontmatter, removes import statements, and cleans .mdx content to generate .md files.
   • Outputs clean .md files alongside HTML during build.

2. File URL Structure:

   • Standard documentation URLs (HTML): https://block.github.io/goose/docs/quickstart
   • Corresponding markdown export: https://block.github.io/goose/docs/quickstart.md

3. Example Usage:

   • curl https://block.github.io/goose/docs/quickstart.md
   • curl -s https://block.github.io/goose/docs/quickstart.md | glow -p

---

Local Development & Testing Enhancements

1. Static File Server:

   • Added serve-static.js, a simple HTTP server to test local builds.
   • Properly handles the /goose/ base URL to align with production deployment.
   • Redirects the root path / to /goose/ to avoid confusion.

2. New npm Script for Testing:

   • Added "serve-static": "node scripts/serve-static.js" to package.json for a smoother developer experience.
   • Test markdown routes locally:
     • http://localhost:3001/goose/docs/quickstart.md

3. Config Updates:

   • Registered the markdown export plugin in docusaurus.config.ts.
   • Updated the deprecated onBrokenMarkdownLinks to the proper markdown.hooks namespace.

---

Changes Made

New Files

• plugins/markdown-export.cjs:
  • Custom plugin to cleanly export .md files during the Docusaurus build process.
• scripts/serve-static.js:
  • Local testing server for static file serving with proper /goose/ path handling.

Modified Files

• docusaurus.config.ts:
  • Added the markdown export plugin configuration.
  • Fixed the onBrokenMarkdownLinks configuration.
• package.json:
  • Added serve-static npm script.

Type of Change

• Feature
• Bug fix
• Refactor / Code quality
• Performance improvement
• Documentation
• Tests
• Security fix
• Build / Release
• Other (specify below)

AI Assistance

• This PR was created or reviewed with AI assistance

Testing

Testing Locally with the Static File Server:

npm run serve-static

Access URLs:
Homepage: http://localhost:3001/goose/
Regular page: http://localhost:3001/goose/docs/getting-started/installation/
Markdown page: http://localhost:3001/goose/docs/guides/recipes/recipe-reference.md

[github-actions]

PR Preview Action v1.6.0
Preview removed because the pull request was closed.
2025-11-21 21:40 UTC

[blackgirlbytes]

Stellar job! As discussed, Emma will add a dropdown button that says view as markdown or something so that users will know this feature exists.