Macros

Rock Chisel ships with useful Jinja2 macros that insert HTML elements that are otherwise annoying to hand code or remember how they work. Using Macros is 100% optional - if you would rather include the HTML equivalents, you can.

These macros are defined in macros.j2, which is a file you can override inside a theme, or inside an individual documentation project, you may wish to create a file called 'user_macros.j2' to define your own additional macros.

begin_code and end_code #

This starts a Prism.js block for syntax highlighting. You can pass in any language name that Prism.js supports. An example, itself drawn with Prism.js:

{{ begin_code(language="python") }}
#!/usr/bin/python
print("hello world!")
{{ end_code() }}

Which renders like so:

#!/usr/bin/python
print("hello world!")

doc #

Generates internal documentation links. You don't really need to use this, as anchor tags work fine, but could be a nice way to add some extra styling in a modified theme.



{{ doc("building") }}
{{ doc("community", "The Community Chapter") }}

It renders as you might expect:

link #

{{ begin_code(language='python') }}
{{ link('http://google.com', 'Google') }}
{{ end_code() }}

This is just like doc but for external links. We suspect you can tell what it does.

begin_info_block & end_info_block


{{ begin_info_block() }}
Don't forget to press the button every 108 seconds.
{{ end_info_block() }}

This puts in an info block like so:

Don't forget to press the button every 108 seconds.

begin_warn_block and end_warn_block #


{{ begin_warn_block() }}
I am the Bad Wolf. I create myself. I take the words. I scatter them ... in time, and space
{{ end_info_block() }}

This puts in an info block like so:

I am the Bad Wolf. I create myself. I take the words. I scatter them ... in time, and space

quiz #


{{ quiz(
  id="quiz1",
  question="What is the average airspeed velocity of an unladen swallow?",
  a="7.2 meters per second",
  b="32 cubits per metric ton",
  c="is that an african or european swallow?",
  d="I don't know that",
  answer="c",
  if_correct="Impressive. You may cross.",
  if_incorrect="I'm sorry."
) }}

Inserts a multiple-choice comprehension quiz in to the document. This is intended to enhance reader comprehension and make the documentation more interactive.

What is the average airspeed velocity of an unladen swallow?

table_of_contents and section #

The table of contents on this exact page and each section header were rendered by macros like this, throughout the page. They are not required to be used on each page but can be useful to help the reader jump to sections of interest in larger chapters.



   Towards the top of the page ...

   {{ table_of_contents() }}

   To start each section ...

   {{ section("Why Most Math Is Imaginary") }}

   To start another section...

   {{ section("Calculus Jokes") }}