Skip to content

Add markdown serving for AI-readable documentation#363

Draft
Claude wants to merge 2 commits intomainfrom
claude/serve-markdown-doc-pages
Draft

Add markdown serving for AI-readable documentation#363
Claude wants to merge 2 commits intomainfrom
claude/serve-markdown-doc-pages

Conversation

@Claude
Copy link
Contributor

@Claude Claude AI commented Feb 18, 2026

Implements clean markdown endpoints for all documentation pages to enable better AI tool parsing. Each page becomes available at URL.md (e.g., /getting-started/clients.md) with navigation, footers, and theme elements stripped.

Changes

  • Jekyll plugin (_plugins/markdown_generator.rb) - Automatically generates .md versions during build by creating shadow pages with clean markdown layout
  • Clean layout (_layouts/markdown.html) - Renders page title, description, and content only, no chrome
  • GitHub Actions workflow (.github/workflows/pages.yml) - Custom build pipeline supporting Jekyll plugins (GitHub Pages default build doesn't support custom plugins)
  • Theme configuration - Switched from remote_theme to local theme in _config.yml to enable plugin usage
  • Dependencies (Gemfile) - Added just-the-docs and required Jekyll plugins

Limitations

Content negotiation via Accept: text/markdown header requires server-side routing unavailable in GitHub Pages static hosting. The .md URL suffix provides equivalent functionality without server configuration.

Example

HTML: https://docs.falkordb.com/cypher/indexing/vector-index
Markdown: https://docs.falkordb.com/cypher/indexing/vector-index.md
Original prompt

This section details on the original issue you should resolve

<issue_title>Documentation AI Readable - Serve .md files</issue_title>
<issue_description>- [ ] Serve markdown versions of your doc pages
For each documentation page, serve a .md version at the same URL with .md appended. AI tools can parse markdown much better than HTML.

  • Fix your markdown page responses
    Your .md URLs should return valid markdown content, not HTML or error pages. Check that your server properly handles .md file requests.

  • Support Accept: text/markdown content negotiation
    When a request includes an Accept: text/markdown header, your doc pages should return markdown content instead of HTML. This lets AI tools request the format they prefer without needing a separate .md URL.

  • Clean up your markdown output
    Your markdown versions include navigation, footer, or other non-content elements. Strip these to give AI clean, focused content.</issue_description>

Comments on the Issue (you are @claude[agent] in this section)

Co-authored-by: gkorland <753206+gkorland@users.noreply.github.com>
uses: actions/checkout@v4

- name: Setup Ruby
uses: ruby/setup-ruby@v1

Check warning

Code scanning / CodeQL

Unpinned tag for a non-immutable Action in workflow Medium

Unpinned 3rd party Action 'Build and Deploy Jekyll Site' step
Uses Step
uses 'ruby/setup-ruby' with ref 'v1', not a pinned commit hash
@Claude Claude AI changed the title [WIP] Add support for serving markdown documentation files Add markdown serving for AI-readable documentation Feb 18, 2026
@Claude Claude AI requested a review from gkorland February 18, 2026 23:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation AI Readable - Serve .md files

2 participants