Update Tips and Tricks documentation for raw / endraw tags

[lhw-1]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:

Updates the documentation for the {% raw %}{% endraw %} tags to be more reader friendly. This change is made in the Tips and Tricks - Using raw/endraw tags to display contents seciton.

This issue was initially brought up in #762, which was resolved by the introduction of the raw / endraw tags in #1220. As this was already resolved, the issue #1835 was modified from a bug report to a documentation update. This PR hence resolves#1835 by addressing the suggestion to make the documentation for this feature more reader-friendly.

Anything you'd like to highlight/discuss:

While editing this part of the documentation, I initially wanted to use the code / output boilerplate like the ones currently being used in the Formatting Contents section, like such:

<includesrc="codeAndOutput.md" boilerplate><variablename="highlightStyle">markdown</variable><variablename="code" id="list-example">
{{ '{{' }} '{{' {{ '}}' }} content {{ '{{' }} '}}' {{ '}}' }}
</variable></include>

However, this seems to result in a compilation error with the following error message:

Invalid expression: missing ) after argument list in
_s(' {{ ')+" content "+_s(')+" ' }}"
Raw expression: {{ ' {{ ' }} content {{ ' }} ' }}

Meanwhile, this:

<includesrc="codeAndOutput.md" boilerplate><variablename="highlightStyle">markdown</variable><variablename="code" id="list-example">
{{ '{% raw %}' }} content {{ '{% endraw %}' }}
</variable></include>

resulted in the following output on a test site:

As this is unrelated to the documentation update, it will be posted as a separate bug report. In any case, this is the reason why the code / output boilerplates were not used in this documentation update. (Any alternative suggestions would be great!)

Update: the issues #2119 and #2120 were opened to address these two bugs.

Apart from this, there are two more suggestions I would like input on, as they may / may not unnecessarily bloat the documentation:

1. Would it be helpful to include this section on Support for Nunjucks as a dropdown / content fragment in the Tips and Tricks - Using raw/endraw tags to display contents section?

2. Would it be helpful to include this Tips and Tricks - Using raw/endraw tags to display contents section as a dropdown / content fragment in the Math Formulae section, or any other relevant section?

Testing instructions:

Proposed commit message: (wrap lines at 72 characters)

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[tlylt]

Some suggestions:

• reword this section to highlight how raw-endraw is used to escape nunjucks (in general), and highlight the more specific cases of {{ content }} and also for example the case in the original report {% raw %}{% set title= "your title here" %}{% endraw %}
• take this opportunity to explain how to add v-pre properly, instead of the currently unlinked markdown-it-attrs which can be confusing to readers who are unfamiliar to this package

Would it be helpful to include this section on Support for Nunjucks as a dropdown / content fragment in the Tips and Tricks - Using raw/endraw tags to display contents section?

👍

Would it be helpful to include this Tips and Tricks - Using raw/endraw tags to display contents section as a dropdown / content fragment in the Math Formulae section, or any other relevant section?

There's already the following mention in the math formulae part, you can move this warning into the tips and then include the tips back in the math section
https://markbind.org/userGuide/formattingContents.html#math-formulae:~:text=If%20your%20equation%20requires%20special%20Nunjucks

[lhw-1]

Thanks for the detailed suggestions @tlylt - I agree with all of them. I'll update accordingly!

[lhw-1]

Updates in commit 76ac122:

reword this section to highlight how raw-endraw is used to escape nunjucks (in general), and highlight the more specific cases of {{ content }} and also for example the case in the original report {% raw %}{% set title= "your title here" %}{% endraw %}

Explanations for why this syntax could sometimes be an issue was added (with reference to the built-in Nunjucks support in MarkBind).

Which specific cases for {{ content }} did you have in mind @tlylt?

take this opportunity to explain how to add v-pre properly, instead of the currently unlinked markdown-it-attrs which can be confusing to readers who are unfamiliar to this package

The phrase on markdown-it-attr was removed, and instead an example on how to add the v-pre as an HTML attribute has been added.

I've also included the section on Support for Nunjucks as a link instead (as part of the explanation) in Tips and Tricks - Using raw/endraw tags to display contents section, and modified the Math Formulae section according to the suggestion by @tlylt above.

In addition, I think that it may be useful to include this also as a tip box within the Formatting Contents - Code section, as this syntax was an issue I encountered while converting the Vue.js documentation to MarkBind, and it was mostly the code blocks that had the {{ content }} syntax. Any suggestions on where within this section to put this tip box?

[tlylt]

reword this section to highlight how raw-endraw is used to escape nunjucks (in general), and highlight the more specific cases of {{ content }} and also for example the case in the original report {% raw %}{% set title= "your title here" %}{% endraw %}

Explanations for why this syntax could sometimes be an issue was added (with reference to the built-in Nunjucks support in MarkBind).

Which specific cases for {{ content }} did you have in mind @tlylt?

I'm referring to exactly this one case of {{ content }}, as in this use of curly brackets for variables.

In addition, I think that it may be useful to include this also as a tip box within the Formatting Contents - Code section, as this syntax was an issue I encountered while converting the Vue.js documentation to MarkBind, and it was mostly the code blocks that had the {{ content }} syntax. Any suggestions on where within this section to put this tip box?

Should be ok at the end of the section.

[lhw-1]

Updates in commit 22379a3:

I've added a more specific example of {{ username }}, taken from the Nunjucks documentation. I've also added in a new subsection under the Formatting Contents - Code section on displaying {{ content }} raw.

[tlylt]

Thanks @lhw-1 for applying the changes, some more nits.

[tlylt]

@lhw-1 pls remember to include the Proposed commit message in the future.