feature: HTML to Markdown (component & routes)

[jbmoelker]

Changes

Making our HTML pages available as Markdown is of interest to some people and especially suitable for software such as LLM's. These changes make HTML content available as Markdown.

• Adds a ToMarkdown component to render HTML as Markdown (works both run- and build-time).
• Adds a [locale]/[...path]/index.md.astro route to render matching route as Markdown (works both run- and build-time).
• Adds post build script to rename Markdown routes to .md as Astro always generates .md/index.html files.
• Adds support for Github Flavoured Markdown, including tables.

See decision log entry for background.

Associated issue

N/A

How to test

1. Open preview link
2. Navigate to a page, like /en/documentation/getting-started/
3. Replace the trailing slash with .md, like /en/documentation/getting-started.md
4. Verify the page is now rendered as Markdown.
5. Navigate to a page with tables, like /en/demos/tables-demo.md
6. Verify that tables are rendered to Markdown.

Checklist

• I have performed a self-review of my own code
• I have made sure that my PR is easy to review (not too big, includes comments)
• I have made updated relevant documentation files (in project README, docs/, etc)
• I have added a decision log entry if the change affects the architecture or changes a significant technology
• I have notified a reviewer

[jbmoelker]

HTML entities in the content are still encoded (< becomes < etc). This is not the cause of the ToMarkdown component as it also happens with the HTML comment below. So Astro forces this higher up I believe. Haven't been able to stop encoding or force decoding 🤷 .

[jbmoelker]

I wanted to write these and others as test. But while this component works in a route, I'm not able to isolate the output properly. 🤷 .

[jbmoelker]

Could keep this in index.astro and try to import it in index.md.astro. I like this separate file as it makes it more clear it can be used across routes. And it also obfuscated the content of index.astro a bit. So I'm happy with this.

[jbmoelker]

I like this pattern where the Page from index.astro can remain unmodified and this route does all the ToMarkdown magic. If a developer using Head Start doesn't need this behaviour, this index.md.astro route can simply be removed.

[jurgenbelien]

It works (apart from the html entities) and there are some changes that are IMHO beneficial to the project regardless (moving staticPaths to separate file).

I do wonder if this functionality makes sense out of the box, instead of adding it later on for a project that needs it. For starters this increases build time for every project, even if they don't use it. A developer might remove the markdown route but forget the link tag, serving erroneous alternates that might negatively impact SEO.

[jurgenbelien]

Suggested change

	Making our HTML pages available as Markdown is of interest to some people and especially suitable for software such as LLM's. Using `Astro.slots.render` seems to be the only solution that works both during build- and run-time.
	Making our HTML pages available as Markdown is of interest to some people and especially suitable for software such as LLMs. Using `Astro.slots.render` seems to be the only solution that works both during build- and run-time.

[jurgenbelien]

Suggested change

	A componanion `.md.astro` route with a `ToMarkdown` component that leverages `Astro.slots.render` to get a usable HTML string, which can be used to transform to Markdown (and other formats):
	A companion `.md.astro` route with a `ToMarkdown` component that leverages `Astro.slots.render` to get a usable HTML string, which can be used to transform to Markdown (and other formats):

[cloudflare-workers-and-pages]

Deploying head-start with    Cloudflare Pages

Latest commit:	9d43842
Status:	🚫  Build failed.

View logs