Skip to content

GITHUB-PAGES-LIQUID.md

Latest commit

 

History

History
50 lines (31 loc) · 1.53 KB

GITHUB-PAGES-LIQUID.md

File metadata and controls

50 lines (31 loc) · 1.53 KB

🌐 GitHub Pages + Liquid: Avoiding Template Collisions

GitHub Pages builds your repository with Jekyll, which uses the Liquid templating language. Oh My Posh themes and documentation often include Go template snippets like:

{{ .Path }}
{{ if .Error }}...{{ end }}

Unfortunately, Liquid also treats {{ ... }} as templates, which can break the Pages build.

✅ The Fix We Use

For any Markdown file that contains Oh My Posh template snippets ({{ ... }}), we wrap the file in Liquid “raw” guards so Jekyll renders the text literally:

<!-- &#123;% raw %&#125; -->
...markdown that contains {{ ... }}...
<!-- &#123;% endraw %&#125; -->

Why the HTML comments?

  • GitHub Pages/Jekyll still sees &#123;% raw %&#125; / &#123;% endraw %&#125; even inside HTML comments.
  • GitHub’s normal README renderer won’t show those lines.

🧾 Which files need this?

Any .md file that includes Oh My Posh templates (especially {{ ... }}) should use the wrapper.

Common examples:

  • Theme docs with template examples
  • Guides that show segment template strings
  • CHANGELOG entries containing prompt templates

🧰 git-cliff (CHANGELOG) note

git-cliff regenerates CHANGELOG.md. To avoid re-breaking Pages, our cliff.toml adds the same raw guards in the generated header/footer.

If you create a new changelog template/config, keep the raw guards.

If Pages fails again with a Liquid error, search for &#123;&#123; in .md files and add the wrapper.