docfx v3 - LiquidTemplate.cs - Render() - liquid file name

[VaclavElias]

I am using Visual Studio and VS doesn't know anything about liquid by default (why would it? 🤷‍♂️🤣).

What do you think if you wouldn't restrict the template name to name.html​.liquid but allow to name the templates just with .html without the .liquid, including the files in the _include folder.

v3 include syntax should also allow us to use html {%- include main.html -%} so we could have the HTML syntax in the include files as well.

The current implementation should remain but could be extended to allow html files 🤣.

Just to clarify, the templates/includes even with .html file extension names still contain the liquid syntax.

Advantages:

• We would gain HTML syntax highlighting in the VS for any html file which can coexist with liquid syntax by default. Obviously the liquid syntax wouldn't be highlighted
  • ✅ this could be mitigated by @KalleOlaviNiemitalo suggestion
• We would get better readability for the HTML
  • ✅ this could be mitigated by @KalleOlaviNiemitalo suggestion
• This is similar to Jekyll and so easy to reuse in both worlds
• New: We could use pure HTML snippets/partials which doesn't contain any liquid syntax so this example {%- include main.html -%} would do exactly what is says, include html template (in Jekyll, it goes the same pipeline like liquid so it can still contain liquid syntax even it is .html)

docfx/src/docfx/template/liquid/LiquidTemplate.cs

Line 41 in 0cdc169

var template = LoadTemplate(new PathString($"{templateName}.html.liquid"));

What are your thoughts?

[paulushub]

Have you read about? Naming rule for a Renderer file

[VaclavElias]

Regarding mustache template, I am not familiar with this syntax so I would leave others to do it. I am going to create an example template where all my updates can be seen in action.

[paulushub]

I am going to create an example template where all my updates can be seen in action.

That will be cool, looking forward to it.

[VaclavElias]

Here is my example and instructions in this repo https://github.com/VaclavElias/docfx-website

Just a quick summary:

• you need my docfx v3 updates
• template if you want to play with the layouts
  • you can point directly to remote repo through https:// or to a local folder like in the example website
• optionally my website to see examples
  • this is pointing to local template

My examples website

[paulushub]

Looking good, how about Github Pages output for preview?
The page/part content seems to be largely markdown, any need for the HTML file extension?

[VaclavElias]

Looking good, how about Github Pages output for preview?

I will try to find out..

Edited: It would be similar process to this https://www.jamescroft.co.uk/building-net-project-docs-with-docfx-on-github-pages/#Create_a_deployment_for_DocFX_site_to_GitHub_Pages it just need to be updated with docfx v3

The page/part content seems to be largely markdown, any need for the HTML file extension?

The html-page.html example page became busy with lots of examples so it lost a purpose in this case but the point for html file extension is to have a choice. Some people might preference for markdown pages while others for html pages. The implementation was trivial so as I mentioned in this discussion somewhere above, there is no reason to restrict it just for markdown files if someone would like to use only html. Again, their choice if html page contains only markdown or it is 50:50 or the html is majority.

In this case, you can just rename the file to html-page.md and the output is going to be the same at the moment, because html is using the same pipeline as md.

There is also another reason in jekyll to process other/any file extensions. For example, you can use sitamap.xml (any xml file) and through liquid syntax generate proper xml markup by using global variables site.pages and site.posts.

Or for search.json, through liquid generate search content or any json content.

I have also added summary to my examples above..

[KalleOlaviNiemitalo]

Can't you map liquid to the HTML editor in Visual Studio? https://docs.microsoft.com/visualstudio/ide/reference/options-text-editor-file-extension?view=vs-2019

[VaclavElias]

Thank you @KalleOlaviNiemitalo, I updated my original post with your suggestion which works and I use it right now.