is:raw directive.

[natemoo-re]

Implementation PR

is:raw

The is:raw directive instructs the Astro compiler to treat any child content as raw text.

This is technically a formalization of the undocumented data-astro-raw attribute that is used internally. I'm bringing this discussion up here to be transparent about formalizing this previously private API, but I'm not sure if we need to go through the full RFC process for something that already exists but would be renamed.

is:raw is particularly useful when non-HTML content (such as KaTeX, Nunjucks, or even PHP) needs to be embedded inside of an Astro file.

This feature can be used to emulate Astro's <script> and <style> behavior in custom components. The compiler ignores everything inside this component until it reaches the closing pair, just like how HTML handles it in <script> or <style>. {expressions} will not be parsed inside of is:raw blocks, nor will any HTML content.

Examples

is:raw is useful for embedding content where {} might be significant characters, such as KaTeX.

<!-- input -->
<code is:raw>c = \\pm\\sqrt{a^2 + b^2}</code>

<!-- output -->
<code>c = \\pm\\sqrt{a^2 + b^2}</code>

is:raw can be used with Fragment to avoid code that would correctly break the Astro compiler, such as an orphaned closing tag.

<!-- input -->
<div>
  <Fragment is:raw></slot></Fragment>
</div>

<!-- output (invalid HTML, but maybe you need that?) -->
<div>
  </slot>
</div>

is:raw can also be used with Component nodes to treat all children as raw text. Paired with a proper Astro.slots API (TODO), this could allow preprocessing of content similar to the built-in Markdown component.

<!-- input -->
<Component is:raw><(9999999>sdsgsgdj90 {}</Component>
<!-- output -->
<div id="component-output"><(9999999>sdsgsgdj90 {}</div>

[tony-sull]

A couple related bug, both were hitting issues with KaTeX syntax likely being manipulated before KaTeX got to process it

https://github.com/withastro/astro/issues/2325
withastro/astro#2566