Skip to content

Conversation

@davlgd
Copy link
Contributor

@davlgd davlgd commented Nov 4, 2025

Description

This PR adds a --accept-markdown / SERVER_ACCEPT_MARKDOWN feature. Once enabled, if a GET or HEAD request is received for path/to/file with Accept: text/markdown header, the server checks if a markdown version exists and send it as response. Checked paths are:

  • path/to/file.md
  • path/to/file.html.md
  • path/to/file/index.html.md

Thus it helps to get an existing markdown file of an HTML page on a website which respects llms.txt standard. It states that:

Pages on websites that have information that might be useful for LLMs to read provide a clean markdown version of those pages at the same URL as the original page, but with .md appended. (URLs without file names should append index.html.md instead.)

Agents/LLMs can ask for a page with Accept: text/markdown and get directly the markdown version. Learn more in added documentation.

Motivation and Context

We build our documentation with Hugo which now includes a native llms.txt support. We use SWS as static server but it lacks Accept header configuration/support. So I thought about adding this feature to allow a better discovery of our content in markdown format.

How Has This Been Tested?

I've added tests, tried it with our documentation.

@semanticdiff-com
Copy link

semanticdiff-com bot commented Nov 4, 2025

Review changes with  SemanticDiff

Changed Files
File Status
  README.md Unsupported file format
  docs/content/configuration/command-line-arguments.md Unsupported file format
  docs/content/configuration/config-file.md Unsupported file format
  docs/content/configuration/environment-variables.md Unsupported file format
  docs/content/features/markdown-content-negotiation.md Unsupported file format
  docs/content/index.md Unsupported file format
  docs/mkdocs.yml  0% smaller
  src/cors.rs  0% smaller
  src/fs/meta.rs  0% smaller
  src/handler.rs  0% smaller
  src/headers_ext/accept.rs  0% smaller
  src/headers_ext/mod.rs  0% smaller
  src/lib.rs  0% smaller
  src/markdown.rs  0% smaller
  src/server.rs  0% smaller
  src/settings/cli.rs  0% smaller
  src/settings/file.rs  0% smaller
  src/settings/mod.rs  0% smaller
  src/testing.rs  0% smaller
  tests/fixtures/markdown/article.html  0% smaller
  tests/fixtures/markdown/article.html.md Unsupported file format
  tests/fixtures/markdown/doc.md Unsupported file format
  tests/fixtures/markdown/index.html.md Unsupported file format
  tests/fixtures/markdown/test.html  0% smaller
  tests/fixtures/toml/markdown_disabled.toml Unsupported file format
  tests/fixtures/toml/markdown_enabled.toml Unsupported file format
  tests/markdown.rs  0% smaller

@davlgd davlgd force-pushed the davlgd-accept-markdown branch from 8175fba to 6df2ace Compare November 4, 2025 20:50
Copy link
Collaborator

@joseluisq joseluisq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea of content negotiation. In general, this could be extended in the future to support, for example, language and media (e.g., images) negotiation.

I gave the MR a first review. I will take a second look in the coming hours.

If something is not clear or you need help, just let me know.

@joseluisq joseluisq added enhancement New feature or request v2 v2 release labels Nov 4, 2025
@joseluisq joseluisq changed the title Accept Markdown feature Content negotiation for Markdown files Nov 4, 2025
@davlgd davlgd force-pushed the davlgd-accept-markdown branch from 27d7c97 to c2ab9bc Compare November 5, 2025 08:36
@davlgd
Copy link
Contributor Author

davlgd commented Nov 5, 2025

I've updated following your recommandations, updated tests and added integration tests. Let me know if you need any further modification.

Copy link
Collaborator

@joseluisq joseluisq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Last changes to make, then we should be ready.

@davlgd davlgd force-pushed the davlgd-accept-markdown branch from f551a01 to 4c30fd8 Compare November 5, 2025 19:18
@davlgd
Copy link
Contributor Author

davlgd commented Nov 5, 2025

I've added 2 commits to let you check changes more easily, feel free to squash/remessage them

@davlgd davlgd requested a review from joseluisq November 5, 2025 19:35
Copy link
Collaborator

@joseluisq joseluisq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All fine from my side.
Thanks!

@joseluisq joseluisq merged commit 2c25d82 into static-web-server:master Nov 6, 2025
36 checks passed
@joseluisq joseluisq added this to the v2.40.0 milestone Nov 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request v2 v2 release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants