URL for plain markdown

Support
1

Hi everyone,

I want to use the plain markdown of a site in my Grav Website:
example.com/changelog should be accessable via example.com/changelog.md

I found no docu for this… Think routable could be the right setting, but dont know how to setup.

Background: In my app i would render the markdown in a extra view, and not in a browser.

Thanks for your help.

2

There’s no documentation for this because it’s pretty damn strange TBH :wink:

If I understand correctly, example.com/changelog.md will return raw markdown to the browser, probably as content type text/plain.

I have never done this (not sure anyone has!) but try treating this as just another page content type as documented under Content Types.

The JSON example should be pretty close to what you want. However, instead of using the json_encode Twig filter, you’ll want something to suppress the markdown’s default conversion to HTML. Grav’s page object has a rawMarkdown() method which you may be able to invoke through Twig (page.rawMarkdown() ??), but more likely you will need to write a simple custom Twig function. For hints, see:

Also you probably need to add your custom type to system/config/media.yaml.

Good luck with that! At the very least you should learn a lot. Let us know how you go.

3

Wow, thank you for the answer.
JSON is good to work, i convert the HTML back to markdown :slight_smile:

This don’t work:

{% set payload = {frontmatter: page.header, content: page.content}  %}
{{ page.rawMarkdown() }}

If I find a way to get the raw Markdown, i will post it here.

4

@Suplanus, I have found two alternatives but both not 100% fullfilling your requirements:

  1. Using the url example.com/changelog (without extension)
  2. Using an url with the extension ‘.md’, but cannot use name ‘changelog’.

I’m using theme Quark and use the following folder structure:

pages
├── 01.home
│   └── default.md
└── 02.changelog
    └──default.md

Alternative 1:

  • In file ‘02.changelog/default.md’ add the following to prevent the markdown from being processed into html:
    process:
  markdown: false
  • We also do not want any headers and footers to be added to the output, so we need a dedicated template. Create file ‘/user/themes/quark/templates/markdown.html.twig’ and add the following content:
    {{ page.content }}
    This template will only return the raw content of the changelog page to the browser.
  • Rename the ‘02.changelog/default.md’ to ‘02.changelog/markdown.md’. This will tell Grav to use the new ‘markdown.html.twig’ template.

You should now get the raw markdown when you point the browser to example.com/changelog

Alternative 2:

  • Follow the same steps as above.
  • Add to page ‘02.changelog/markdown.md’ the following to frontmatter:
    append_url_extension: '.md'
  • Out of the box, ‘md’ is not a supported page type. We need to add this type to ‘user/config/system.yaml’:
    pages:
  types: [html,htm,xml,txt,json,rss,atom,md]
                                          ^--- Added 'md' type
  • Rename folder 02.changelog to 02.anyname

You can now point the browser to example.com/anyname.md to get the raw markdown.

Note:

  • If, in alternative 2, you do not change 02.changelog into 02.anyname, Grav will throw a forbidden error. Same will happen when using names of other *.md files inside the root of your Grav installation. E.g readme.md will also throw an error.

  • The forbidden error is probably thrown because .htaccess blocks files with extension .md using two RewriteRules:

    # Block access to specific file types for these user folders
RewriteRule ^(user)/(.*)\.(txt|md|yaml|yml|php|pl|py|cgi|twig|sh|bat)$ error [F]
# Block all direct access to .md files:
RewriteRule \.md$ error [F]

    I have tried to exclude this from happening for file '/user/pages/02.changelog/markdown.md) using a negative lookahead regex, but didn’t succeed.

    I admid, I’m not that well versed in .htaccess

Hope this helps…

5

Great work what you are doing here. Thanks.

I think both variants are not that good for me. But the .htaccess is interesting.

I removed md from it to this:

# Block access to specific file types for these system folders
RewriteRule ^(system|vendor)/(.*)\.(txt|xml|md|html|yaml|yml|php|pl|py|cgi|twig|sh|bat)$ error [F]
# Block access to specific file types for these user folders
RewriteRule ^(user)/(.*)\.(txt|yaml|yml|php|pl|py|cgi|twig|sh|bat)$ error [F]
# Block all direct access to .md files:
#RewriteRule \.md$ error [F]

So the markdown is accessable… I checked the rules set on webserver is 775. Are there any security things that is not that good?
I think perhaps there is a XSS problem when in markdown is evil code… but the code can not be injected!?

Here is the result: https://cuterdio.com/user/pages/07.changelog/default.en.md

Now i have to find a rule to remove the metainfos… i think in my case i can search for the first # starting line.

6

@Suplanus, When you use your own template, as I showed above, frontmatter will not be included in the output.

I would feel hesitant to allow straight access to all *.md files. Not sure what the risks are of files getting contaminated though…

1 Like
7

@Suplanus, When deleting/renaming ‘/CHANGELOG.md’ from my site, the ‘forbidden’ error is gone and the url example.com/changelog.md shows the right content…

Also, instead of defining a url extension, a routing alias can be defined in frontmatter.

Alternative 3:

  • In file ‘02.changelog/default.md’ add the following to prevent the markdown from being processed into html:

    process:
  markdown: false

  • Define an alias to the page to include .md:

    process:
  markdown: false
routes:
  aliases:
    - '/changelog.md'

  • We also do not want any headers and footers to be added to the output, so we need a dedicated template. Create file ‘/user/themes/quark/templates/markdown.html.twig’ and add the following content:

    {{ page.content }}

    This template will only return the raw content of the changelog page to the browser.

  • Rename ‘02.changelog/default.md’ to ‘02.changelog/markdown.md’. This will tell Grav to use the new ‘markdown.html.twig’ template.
  • Delete/rename file /CHANGELOG.md from/in the root of your Grav installation.

You should now get the raw markdown when you point the browser to example.com/changelog.md