If you've upgraded a live site to 2.1.x recently, there's a new feature you might have missed. I thought I should point it out here because it might not be something you want.
It's already been added but it has an opt-out, so I'm doing this as a sort of PSA in case you want to turn it off or tweak it. The feature is not documented yet anywhere that I've seen except in the CHANGELOG where I noticed it. It's integrated and described in the Admin2 plugin interface, so you might have noticed it there too.
This feature supports adding .md to any visible URL path on the site to expose the page's markdown and YAML frontmatter. It's apparently so that agents can traverse the site and consume its content more easily. There's also a feature enabled by default which appends links to parent and sibling pages to the end of the markdown under the markdown level 2 heading "Navigation". I assume this substitutes for the site's navigation menu which would be missing in its markdown.
The new agent pages are served as mime type "text/markdown". When they are enabled, references to the new markdown versions are served in HTTP via a Link header and in the HTML head with <link rel="alternate" … assuming your theme sources Grav core's metadata partial template.
Here's an example of what one of these pages might look like:
---
title: Services
url: 'https://example.org/services'
markdown: 'https://example.org/services.md'
lang: en
date: '2020-10-18'
description: 'Descriptive metadata bla bla ipsum lorem.'
---
# Services
## Services
### Markdown starts with a 3rd level heading taken from this page's content
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
- bullet
- bullet
- etc
---
## Navigation
- Previous: [About](https://example.org/about.md)
- Next: [Work Status](https://example.org/work.md)
Notes:
- the frontmatter seems to be a selective rewrite of the frontmatter of the source file in
user/pages - the heading hierarchy has been altered
- my "*" bullets were converted to "-" in content markdown (probably irrelevant)
- an HTML comment in the page has been stripped (although I'm aware it's not in the HTML version!)
- the "Navigation" section has been added, as mentioned.
I'm going to create at least a stub PR adding the new options to Grav Learn. To introduce them here, it's easiest to glean all of the sub-options from the inline comments:
pages:
# …
markdown_output: # Serve any page as Markdown for AI agents and other text clients
enabled: true # Answer `<route>.md` URLs and `Accept: text/markdown` requests with Markdown
frontmatter: true # Start the Markdown with a YAML block: title, url, date, description, taxonomy
links: true # End the Markdown with links to the parent, neighbouring and child pages
max_links: 100 # Most child pages listed in that navigation section (0 for no limit)
absolute_urls: true # Turn root-relative links and images into absolute URLs
token_header: true # Send an `X-Markdown-Tokens` header with an estimated token count
So if you want to opt out of this for any of your Grav 2.1+ sites, make sure pages.markdown_output.enabled is false in user/config/system.yaml.
In the Admin panel, it looks like you need to find the Markdown Output section in the Content tab under System settings (something like that). There you can find all of these options and there's slightly more explanatory help text than shown above.
I hope this is useful to some of you.