RoamJS is becoming a part of SamePage! To check out the inter-tool network we're building, click here to learn more!

UNDER DEVELOPMENT

TEMPLATES

Table of Contents

  7. Advanced Features

Main Template

In the settings panel of the roam/js/static-site page, there will be a tab towards the bottom called "Template". This will take you to an HTML code editor showing you what template is currently used for all pages.

If there are any changes you'd like to make to all of your webpages, this is the best place to do so. For example, if you would like to add a page title to the top of all of your pages, you would just need to add this line right below the first content div:

<h1 id="content-header">${PAGE_NAME}</h1>

This is also a good place to add any prebuilt themes or external JavaScript that you would like to apply to all pages, by linking to those assets right before the closing </head> tag.

If after numerous edits you prefer to reset the template to the original value that came with the extension out of the box, simply click on the reset icon on the top right.

Variables

In the default template, you will notice several segments of the form ${PAGE_*}. Each of these segments act as variables that are replaced by a value depending on which page of your website is rendered.

To specify a variable and value for a page, create a block with the attribute roam/js/static-site/*:: where the * in the attribute matches the * in the variable you are targeting. Then you could place the value of that attribute in the same block or as the first child of that block.

For example, if you have a page called Blog, you may want to create a block on that page that says roam/js/static-site/description:: The home page for all of my writing. Now whenever you visit the Blog page on your website, all of the places that say ${PAGE_DESCRIPTION} will be replaced with the text The home page for all of my writing.

Hint: If you do not want these attributes to show up on your site, be sure to add them as a child of the #roam/js/static-site/ignore tag.

There are some special rules about attribute value resolution:

  1. The attribute value will be the text on the same block of the attribute, or it will take the whole first child block it the rest of the block is empty.

  2. Attribute values that are tags will strip out the # and [[]].

  3. Attribute values that are images will resolve to just the url of the image, not the full ![](url) syntax

  4. Attribute values that are HTML code blocks will resolve to just the content of the code block, ignoring the preceding three backticks, language chosen, and last three backticks.

  5. Attribute values that are JS code blocks will resolve to the output of dynamically running this code block. The variable uid will be defined and map to the page uid of the current page. If any error is thrown, the full block text value will be returned instead.

There are also some special variable names:

  • PAGE_CONTENT - Resolves to the content on the page

  • PAGE_NAME - Resolves to the title of the page by default. However, this could be overridden with the roam/js/static-site/name attribute in case you want the name in Roam to differ from the title of the page on the website.

  • PAGE_REFERENCES - Resolves to the page references that reference the current page. The references will each resolve according to the configured Reference Template

Reference Template

The Reference Template is a special template that dictate how each reference to the current page is outputted to your webpage.

The Reference Template supports two special variables of its own:

  • REFERENCE - resolves to the name of the page referencing the current page.

  • LINK - the url to the page referencing the current page.

If you would like to remove rendering references entirely from the webpage, then simply remove the ${PAGE_REFERENCES} variable from the template (as well as probably the surrounding div and ul tags).