How can I use my-file.md naming instead of my-file.html.md in Pages?

[HiRolla]

Hello! I'm happy to use Pages with my markdown Obsidian vault files. But i've found out that Pages does not process my-file.md. Only if I rename it's tail into .html.md I can se this file in Joomla.

Is there any way to deal with my-file.md naming?

[johanjanssens]

Pages uses a file naming convention as follows [filename].[format].[engine]

• filename: is the actual name of the file, if the Page doesn't contain metadata the page slug and name are using the filename.
• format: is the actual format of the page, it allows pages to support different output format, html, json, rss, etc.
• engine: is the rendering engine used, at present we support two engines out of the box php, and md (markdown)

The markdown engine makes use of: https://michelf.ca/projects/php-markdown/ currently Pages ships version 1.9.0.

Pages also support exceptions for static files that don't need a rendering engine. Following file are included as is:

• html
• txt
• svg
• css
• js

This means you do not need to add a [engine]to their filename, when importing any of these file types, the content will just be copied in place.

Your problem, and possible workarounds

The file naming convention is enforced and I have chosen not to allow to deviate from it as it makes the code quite a bit more complex, prefer to stick to solid conventions.

With that said, a solution could be too exclude md from being considered a template engine. You can do that by adding it to the excludes_types config option of the template object.

<?php

return array(

    // Extensions
    'extension_config' => [

        'com:pages.template'  => [
            'excluded_types' => ['md']
        ]
    ]
);

For a config example see: https://github.com/joomlatools/joomlatools-pages/blob/master/contrib/sites/blog/config.php

With this in place Pages will no longer process .md files, instead it will just copy the file content when you include the file. You can then:

1. Inline partial

Use the inline partial filter to render the markdown to html as follows:

<ktml:partial format="md">
   <?= import('/path/to/file.md'); ?>
</ktml:partial> 

2. Markdown filter

Use the markdown page filter to double render the whole page, it will render any markdown it finds to html. Simple add the filter to the page frontmatter

---
@process:
    filters: [markdown]
---

Notes

• I haven't tested this, wrote the above by head so cannot guarantee it works, it might require a bit of extra tinkering.

• The /path/to/file.mdstill requires the path to be where Pages can located the file. If you are putting the md files outside of your /joomlatools-pages/pages pages won't be able to find them. This can be solved but requires adding another template locator

Best approach: use data files

The easiest way to do this would be to use data files and the Data API, this will work out of the box.

The data API is a very powerful API, it allows you to load any kind of data from structured data files, and it also offers special support for markdown files, even markdown files with frontmatter.

If the format of the data file is Markdown (.md) the contents of the file will be available as data('file')->content and it will be rendered to html for you on the fly.

Data files can be loaded from anywhere too by adding special namespaces for them: #256

This should get you started. If the above doesn't work would need to look into adding more flexibility to Pages to handle the use-case.

Happy coding!