generate-roam-site
TypeScript icon, indicating that this package has built-in type declarations

2.14.10 • Public • Published

generate-roam-site

Generate a static site from a Roam Graph.

Requirements

You must have a version of google chrome installed.

Windows: C:\Program Files (x86)\Google\Chrome\Application\chrome.exe

Linux: /usr/bin/google-chrome-stable

Usage

import run from "generate-roam-site";

await run({
  roamGraph: "dvargas92495",
  roamUsername: "dvargas92495@gmail.com",
  roamPassword: process.env.ROAM_PASSWORD,
}).then(() => console.log("Success!"));

Roam Configuration

Most other configuration happens from your Roam DB, on a page called roam/js/static-site. For legacy reasons, roam/js/public-garden is also supported as a valid configuration page name. The following configuration options are supported:

  • Index - The page name that will serve as the entry point of the site. Could be raw text or a page link.
  • Filter - A set of rules that specifies which pages to build. If a page matches any child rule, it will be built into the site. The following rules are supported:
    • Starts With - If a page starts with the given text, it will be included in the site. Useful for namespacing, e.g. Article/Article.
    • Tagged With - If a page contains a tag with the given text, it will be included in the site. Includes pages with any form of tags or attributes. Could be raw text or a page link.
  • Template - An HTML Code block that will be used as the template for every generated HTML file.
    • It supports a few variables that can be interpolated:
      • PAGE_NAME - The name of the page
      • PAGE_CONTENT - The content of the page
      • REFERENCES - An array of pages that reference the current page
    • The default template looks like
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>${PAGE_NAME}</title>
    <style>
      .rm-highlight {
        background-color: hsl(51, 98%, 81%);
        margin: -2px;
        padding: 2px;
      }
    </style>
  </head>
  <body>
    <div id="content">${PAGE_CONTENT}</div>
    <div id="references">
      <ul>
        ${REFERENCES}
      </ul>
    </div>
  </body>
</html>
  • Reference Template - An HTML Code block that will be used as the template for every page reference. The REFERENCES variable interpolates to all references each rendered as one instance of the template
    • It supports a few variables that can be interpolated:
      • REFERENCE - The name of the page referencing the current page
      • LINK - The url of the page html file
    • The default template looks like
<li><a href="${LINK}">${REFERENCE}</a></li>

Here's an example configuration, that uses the Personal Website page as the entry point and includes all pages that start with a P:

  • Index
    • Personal Website
  • Filter
    • Starts With
      • P

Here's an example configuration, that uses the Blog Post page as the entry point and includes all pages that are Tagged with Blog Post:

  • Index
    • Blog Post
  • Filter
    • Tagged With
      • Blog Post

Per Page Configuration

You could ignore specific blocks in pages that are included. Nest everything that you would like to keep on the page but have filtered out of the static site under a block that just says [[roam/js/static-site/ignore]].

You could override any roam page's default title with the roam/js/static-site/title:: attribute. The value set to the right of this attribute will be used in place of the PAGE_NAME variable during template interpolation.

You could add anything to a page's head with the roam/js/static-site/head:: attribute. The HTML code block defined as a child of this block will be injected into this page's head.

Note, that while you'll usually want to have these attributes nested within the ignore block, it's not a strict requirement.

Custom Components

There are many Roam UI elements that render using {{}}. This package includes its own custom UI components on top of the Roam native ones. (Note: not all Roam native components are supported yet.)

Daily Log

On any page, create a {{static site:daily log}} button. The button will be replaced with the blocks where the page is referenced in daily notes. This is an example output:

  • Daily Log:
    • March 29th, 2021
      • Just child blocks
    • March 26th, 2021 Inline
      • And a child block

If there's a block on a daily note page referencing the original page that you would like to be excluded, simply add a #[[roam/js/static-site/ignore]] tag to the block.

Optional Arguments

  • logger - an object specifying which loggers to use for info and error. Defaulted to console
  • pathRoot - an absolute file path denoting where output paths should be relative to. Defaulted to process.cwd().
  • inputConfig - A JSON to override any config options coming from Roam:
    • index - string
    • filter - {rule: string, values: string[]}[]
    • template - string
    • referenceTemplate - string

Readme

Keywords

none

Package Sidebar

Install

npm i generate-roam-site

Weekly Downloads

13

Version

2.14.10

License

MIT

Unpacked Size

64.1 kB

Total Files

16

Last publish

Collaborators

  • dvargas92495