COMMAND REFERENCE

1. Trigger Your Workflow

2. Understanding Commands

3. Using Pre-Defined Workflows

4. Make Your Own Workflows

5. Command Reference

6. Alternative Methods

7. SmartBlocks Store

8. Developer Docs

1. An expression that will resolve to a date

2. Optional parameter that tells SmartBlocks to not return a Roam formatted date, but a date formatted in the format you specify. Supported date formats defined here: https://date-fns.org/v2.22.1/docs/format. Examples:

   • yyyy-MM-dd: 2020-10-12

   • MMM dd: Oct 12

   • ww: 42

• <%DATE:Today%>

• <%DATE:Friday%>

• <%DATE:Friday%>

• <%DATE:5 days from now%>

• <%DATE:In two weeks%>

• <%DATE:In two weeks,yyyy-MM-dd%>

• DATE also supports special abbreviations:

  • DBOM or DEOM = Beginning/End of month

  • DBONM or DEONM = Beginning/End of next month

  • DBOY or DEOY = Beginning/End of year

  • DBONY or DEONY = Beginning/End of next year

1. An optional expression that can resolve to a time

• <%TIME%>

1. An optional expression that can resolve to a time

• <%TIMEAMPM%>

• Video explanation of DATEBASIS:

• This command sets the mode for the workflow. You can change between modes in one workflow.

1. Date basis to be used in the workflow

   • If DNP - will use the date of the Daily Notes Page if the workflow is run on a DNP, otherwise will still use today.

   • Otherwise provide a natural language date command to determine the date basis

• <%DATEBASIS:DNP%>

  • Uses the Daily Note Page date that the workflow is run on, if it's not a DNP it will use Today's date

• <%DATEBASIS:today%>

  • Use today's date as the basis

• <%DATEBASIS:in 3 days%>

  • Use the date 3 days from now as the date basis

• <%DATEBASIS:in two weeks%>

• <%RANDOMBLOCK%>

1. Page to pull a child from. Could be either:

   • Option 1: Page name or tag name (brackets [[]] or hashtag # are optional)

   • Option 2: Parent block UID

2. Levels within the page to include. Specifying 0 includes all blocks

3. Format to output the block in. See our Formatting section for more info.

• <%RANDOMBLOCKFROM:Evergreen Notes%>

• <%RANDOMBLOCKFROM:935dpJL8X%>

• <%RANDOMBLOCKMENTION:Evergreen Notes%>

• Option 1: Page name or tag name (brackets [[]] or hashtag # are optional)

• Option 2: Parent block UID

• <%RANDOMCHILDOF:Evergreen Notes%>

• A Minimum value

• A Maximum value

• <%RANDOMNUMBER:1,10%>

• <%RANDOMPAGE%>

• Purpose: Returns a list of block references of TODOs for today

• Parameters:

  1. Maximum amount of block references to return. Default value is 20

  2. Format to output the block in. See our Formatting section for more info.

  3. optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

     • toRead,Pinnacle

       • returns blocks with toRead AND Pinnacle in the text

     • toRead|Pinaccle

       • returns blocks with toRead OR Pinnacle in the text

     • toRead,-Pinnacle

       • returns blocks with toRead but not if they have pinnacle

• Example: <%TODOTODAY:20,(({uid}))%>

• Purpose: Returns a list of block references of TODOs for overdue TODOs. That is TODOs that have a dated page reference in them.

• Parameters:

  • Maximum amount of block references to return. Default value is 20

  • Format to output the block in. See our Formatting section for more info.

  • optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

    • toRead,Pinnacle

      • returns blocks with toRead AND Pinnacle in the text

    • toRead|Pinaccle

      • returns blocks with toRead OR Pinnacle in the text

    • toRead,-Pinnacle

      • returns blocks with toRead but not if they have pinnacle

• Examples: <%TODOOVERDUE:20,(({uid}))%>

• Purpose: Returns a list of block references of TODOs for overdue TODOs. That is TODOs that have a dated page reference in them. Additionally TODOs that are on a Daily Notes Page (DNP) without a date from the past.

• Parameters:

  • Maximum amount of block references to return. Default value is 20

  • Format to output the block in. See our Formatting section for more info.

  • optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

    • toRead,Pinnacle

      • returns blocks with toRead AND Pinnacle in the text

    • toRead|Pinaccle

      • returns blocks with toRead OR Pinnacle in the text

    • toRead,-Pinnacle

      • returns blocks with toRead but not if they have pinnacle

• Examples: <%TODOOVERDUEDNP:20,(({uid}))%>

• toRead,Pinnacle

  • returns blocks with toRead AND Pinnacle in the text

• toRead|Pinaccle

  • returns blocks with toRead OR Pinnacle in the text

• toRead,-Pinnacle

  • returns blocks with toRead but not if they have pinnacle

• Purpose: Returns a list of block references of TODOs for future TODOs. That is TODOs that have a dated page reference in them. Additionally TODOs that are on a Daily Notes Page (DNP) without a date on a future date.

• Parameters:

  • Maximum amount of block references to return. Default value is 20

  • Format to output the block in. See our Formatting section for more info.

  • optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

    • toRead,Pinnacle

      • returns blocks with toRead AND Pinnacle in the text

    • toRead|Pinaccle

      • returns blocks with toRead OR Pinnacle in the text

    • toRead,-Pinnacle

      • returns blocks with toRead but not if they have pinnacle

• Examples: <%TODOFUTUREDNP:20,(({uid}))%>

• Purpose: Returns a list of block references of TODOs with no date tag nor on DNPs

• Parameters:

  • Maximum amount of block references to return. Default value is 20

  • Format to output the block in. See our Formatting section for more info.

  • optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

    • toRead,Pinnacle

      • returns blocks with toRead AND Pinnacle in the text

    • toRead|Pinaccle

      • returns blocks with toRead OR Pinnacle in the text

    • toRead,-Pinnacle

      • returns blocks with toRead but not if they have pinnacle

• Examples: <%TODOUNDATED:20,(({uid}))%>

1. Text to turn into attribute

• <%ATTRIBUTE:Date%>

• Video Demonstration

1. Maximum amount of block references to return.

   1. if set to -1, will return only count of matches

2. Page name or tag name (This parameter is case-sensitive and must match your page or tag name as used in your graph)

3. Format to output the block in. See our Formatting section for more info.

4. Optional filtering parameters, with support for include and excluding blocks based on their text and the page their in with simple text comparison

• <%BLOCKMENTIONS:15,toRead%>

  • Returns up to 15 blocks that mention #toRead or [[toRead]]

• <%BLOCKMENTIONS:15,toRead,{uid},book%>

  • Returns up to 15 blocks that mention #toRead or [[toRead]] that also have the word "book" in the text of the block

• <%BLOCKMENTIONS:15,toRead,{uid},book,pinnacle%>

  • Returns up to 15 blocks that mention #toRead or [[toRead]] that also have the words "book" and "pinnacle" in the text of the block

• <%BLOCKMENTIONS:15,toRead,{uid},book,-pinnacle%>

  • Returns up to 15 blocks that mention #toRead or [[toRead]] that also have the word "book" but not "pinnacle" in the text of the block

1. Maximum amount of block references to return.

   1. if set to -1, will return only count of matches

2. Page name or tag name (This parameter is case-sensitive and must match your page or tag name as used in your graph)

3. Start date - tasks with a date from start date and beyond until parameter 3 (End Date). Date NLP is supported, so you can do something like: Today, yesterday, 2020-12-31 and other formats.

   1. Set to 0 for no start date

   2. Set parameter 3 and 4 to -1 to have it return blocks that have no date in them

4. End Date - all tasks from the end date and before, until parameter 2 (start date). Date NLP is supported, so you can do something like: Today, yesterday, 2020-12-31 and other formats.

   1. Set to 0 for no end date

5. Sort Order

   • ASC - oldest dated blocks to newest

   • DESC - newest dated blocks to oldest

   • NONE - no date sort defined, just return them alphabetically

6. Format to output the block in. See our Formatting section for more info.

7. Optional filtering parameters, with support for include and excluding blocks based on their text with simple text comparison. Filters are processed before date processing. This means if filters are designed to include or exclude text, they will be processed before the dates are processed.

1. Block Reference UID

   • Add a + to front of UID to get back just the page title

   • Add a - to get back just the path, without the page title

2. Separator to be used to separate each parent

• <%BREADCRUMBS:(( UID )),>%>

  • Will use > as a separator between block refs

• <%BREADCRUMBS:+(( UID )),>%>

  • Returns just the page title

• <%BREADCRUMBS:-(( UID )),>%>

  • Returns just the path blocks, no page title

1. Text of the button

• <%BUTTON:kanban%>

1. Variable name or a block reference.

2. Start index, inclusive, 1 is first

3. End index, inclusive. If 0, it will go to the last child

4. Format to output the block in. See our Formatting section for more info.

5. Levels of children to include. 0 will include all levels (default)

• <%CHILDREN:((abc123def))%>

• <%CONCAT:[,[pageName],]%>

  • outputs [[pageName]]

• <%CONCAT:[,[pageName],]]\, followed by more text%>

  • outputs [[pageName]]], followed by more text

  • Special note: if you want a comma to be a part of the output, put a \ in front of it as in this last example

1. Variable name. If parameter is equal to base, then will return the base page name of a namespaced title instead.

• <%CURRENTPAGENAME%>

• <%CURRENTURL%>

• <%CURRENTUSER%>

1. Name of variable

2. Whether or not to add (()) formatting, defaulted to true. Set to false for just the id.

• <%CURRENTBLOCKREF:varName%>

  • Will store the current block reference into a variable named varName

1. Name of variable

• <%CURRENTBLOCKCONTENT:varName%>

  • Will store the current block reference into a variable named varName

1. Page name or block ref

2. The name of the attribute.

• <%GETATTRIBUTE:ref,Name%>

1. Name of variable

• <%TRIGGERREF:varName%>

  • Will store the current block reference into a variable named varName

• <%RESOLVEBLOCKREF:abcdefghi%>

• <%RESOLVEBLOCKREF:((abcdefghi))%>

1. Maximum amount of block references to return.

2. Format to output the block in. See our Formatting section for more info.

3. string of text to find (CASE-SENSITIVE)

4. Parameter 3 to X: Optional filtering parameters, with support for include and excluding blocks based on their text with simple text comparison. Prefix with - to say that the text shouldn't include a term

1. Text to tag

• <%HASHTAG:Projects%>

1. Text to tag

• <%TAG:<%DATE:today%>%>

1. Content to replace. Can be raw text, a SmartBlock Variable, or a block reference.

2. Expression to search for. Supports wrap in inline code styling.

3. Content to replace with. Can be raw text or a SmartBlock Variable

4. (Optional) regular expression flag. For instance, you could add a g here to replace all instances where the second argument appears.

• <%REPLACE:This is a sentence,sentence,block%>

1. Reference of block to replace. Can be a SmartBlock variable

2. Content to replace with. Can be a SmartBlock variable

• <%UPDATEBLOCK:ref,hello world!%>

1. Reference to grab the parent from

2. Name of variable

3. Whether or not to add (()) formatting, defaulted to true. Set to false for just the id.

• <%PARENT:ref,varName%>

1. Variable to compare

2. Value to compare the variable to

   • If the value starts and ends with /, it will be treated as a Regular Expression

   • If no value is specified, it's the same as checking if the block is empty

• <%IFVAR:foo,true%> - checks if variable foo has value true

• <%IFVAR:foo,/.+/%> - checks if variable foo is not empty

• <%IFVAR:foo,/^$/%> - checks if variable foo is empty

1. Variable to compare

2. Value to compare the variable to

   • If the value starts and ends with /, it will be treated as a Regular Expression

   • If no value is specified, it's the same as checking if the block is empty

• <%IFNOTVAR:foo,true%> - checks if variable foo does not have value true

• <%IFNOTVAR:foo,/.+/%> - checks if variable foo is empty

• <%IFNOTVAR:foo,/^$/%> - checks if variable foo is not empty

1. Variable name or value to compare

2. Variable name or value to compare

   • If the value starts and ends with /, it will be treated as a Regular Expression

• <%IFMATCH:foo,true%> - checks if variable foo has value true. If no variable foo exists, it then checks to see if foo is equal in value to true, which would skip the block

1. Variable name or value to compare

2. Variable name or value to compare

   • If the value starts and ends with /, it will be treated as a Regular Expression

• <%IFMATCH:foo,true%> - checks if variable foo has value true. If no variable foo exists, it then checks to see if foo is equal in value to true, which would keep the block

• If they match, the block is inserted

• If there is no match, the block is not inserted

1. A number from 1 to 31 corresponding to the day in the month. Optionally, a comma separated list of numbers to test for multiple days

• <%IFDATEOFYEAR:07/27%> (Inserts this block if it is July 27th)

• <%IFDATEOFYEAR:01/01,04/01,09/01,12/01%> (Inserts this block if it is the first day of the quarter)

• If they match, the block is inserted

• If there is no match, the block is not inserted

1. A number from 1 to 31 corresponding to the day in the month. Optionally, a comma separated list of numbers to test for multiple days

• <%IFDAYOFMONTH:1%> (Inserts this block if it is the first day of the month)

• <%IFDAYOFMONTH:15,30%> (Inserts this block if it is the it is the 15th or 30th of the month)

• If they match, the block is inserted.

• If there is no match, the block is not inserted

1. A number from 1 to 7, 1 is Monday, 2 is Tuesday and so on. Optionally, a comma separated list of numbers to test for multiple days

• <%IFDAYOFWEEK:7%> (This block will be inserted if today is Sunday)

• <%IFDAYOFWEEK:1,3,5%> (This block will be inserted if today is Monday, Wednesday or Friday)

• If it is, the block is inserted.

• If it isn't, the block is not inserted

1. Page or uid to check

2. A block reference to check

• <%IFTAGINBLOCK:TODO,((block-ref))%>

• <%IFCHILDREN:TODO,((block-ref))%>

• Purpose: prompts user for input which will then be inserted into the block

• Parameters: Parameters in this command are delimited by %%

  1. Text that will be displayed to the user.

     1. Could add a {page} placeholder to turn the input into a Page Input that accepts page values.

     2. Could add a {block} placeholder to turn the input into a Block Input that accepts block values and returns the text.

     3. Could add a {ref} placeholder to turn the input into a Block Input that accepts block values and returns the reference.

  2. Default value for the input

  3. Any number of other options. Specifying 3 or more parameters turn the input from a text input to a dropdown.

• Example 1: (No default value for input)

  • <%INPUT:Attendees for this meeting?%>

• Example 2: (Default value for input)

  • <%INPUT:Attendees for this meeting?%%Jim, Sally, Bob%>

• Example 3: (Dropdown for input)

  • <%INPUT:Guest for this meeting?%%Jim%%Sally%%Bob%>

• Example 4: (Page Input)

  • <%INPUT:Guest for this meeting?{page}%>

1. Variable name

2. Value of Variable

1. Variable name. Should contain only letters and number, no special symbols. Variables are case-sensitive.

• <%GET:MyVariableName%>

1. Variable name. Should contain only letters and number, no special symbols. Variables are case-sensitive.

• <%HAS:MyVariableName%>

• <%CLEARVARS%>

1. Addend to sum

• <%SUM:2,3,4%>

1. The minuend

2. The subtrahend

• <%DIFFERENCE:2,1%>

1. Factor to multiply

• <%PRODUCT:2,3,4%>

1. The dividend

2. The divisor

• <%DIVISION:6,3%>

1. The number to floor

• <%FLOOR:3.14%>

1. The number to round

• <%ROUND:3.14%>

1. The workflow name

2. An optional page name to execute the workflow on another page. The command will return a block reference to the other page if this parameter is set.

• <%SMARTBLOCK:Daily%>

• <%SMARTBLOCK:Daily,<%DATE:Tomorrow%>%>

1. Count of repeats

2. Content to repeat

• <%REPEAT:5,hello%>

• <%CLIPBOARDCOPY:This text is written to clipboard%>

• trim - removes white space in the beginning and end of the pasted text.

• split - splits the pasted text into separate blocks

• nohyphens - removes leading hyphens

• noextraspaces - reduces extra spaces down to one space

• nocarriagereturn - removes the carriage return often found in copies on windows

• returnasspace - replaces returns with a space character instead

• <%CLIPBOARDPASTETEXT%>

• <%CLIPBOARDPASTETEXT:trim,split%>

• <%CURSOR%>

• <%FOCUSONBLOCK%>

• <%EXIT%>

1. Number of seconds the notification is visible

2. Message to be displayed. Supports Markdown rendering

3. Position of the notification. By default it shows on top. Valid values are

   • top

   • bottom

   • top left

   • top right

   • bottom left

   • bottom right

• <%NOTIFICATION:10,Welcome to my SmartBlocks%>

  • Displays the notification for 10 seconds with the text "Welcome to my SmartBlocks"

• <%NOTIFICATION:120,Welcome to my **SmartBlocks**%>

  • Displays the notification for 2 minutes (120 seconds) with the text "Welcome to my SmartBlocks"

1. Page name or block UID

2. Optional effect after navigating. See migration guide for details.

• <%OPENPAGE:My Page%>

• <%OPENPAGE:gk78VGCKW,GOTOBLOCK 1%>

1. Accepts a page name or block reference

2. Optional effect after navigating. See migration guide for details.

• <%SIDEBARWINDOWOPEN:My Page%>

• <%SIDEBARWINDOWOPEN:gk78VGCKW%>

• <%SIDEBARWINDOWOPEN:gk78VGCKW,GRAPH%>

1. Accepts a page name or block reference

• <%OPENREFERENCESINSIDEBAR:My Page%>

1. A number. 0 will close all windows in the right sidebar. Greater than or equal to 1 will close the corresponding sidebar based on its position. Window 1 is at the top and numbers down

• <%SIDEBARWINDOWCLOSE:0%>

• <%SIDEBARWINDOWCLOSE:1%>

1. Accepts one parameter, a value of 1 to 4

   • 1 opens the left sidebar

   • 2 closes the left sidebar

   • 3 opens the right sidebar

   • 4 closes the right sidebar

• <%SIDEBARSTATE:2%>

• <%SIDEBARSTATE:3%>

1. URL

2. Optional Field to return a specific field in the response data. Uses the lodash syntax for nested field values.

• <%APIGET:https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1%>

• #SmartBlock NameOfSmartBlock <%HIDE%>

• #SmartBlock NameOfSmartBlock <%NOCURSOR%>

• {uid} - resolves to the block reference

• {page} - resolves to the page the block originated from

• {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

• {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

• {text} - resolves to the raw text of the block