Scroll started as an extensible alternative to Markdown.

Like Markdown, Scroll is a plaintext language that can build HTML (among other things).

Scroll is minimal to help you reduce your ideas to their essence.

You can extend Scroll by adding your own Parsers to build new microlanguages to fully develop your ideas.

Scroll debuted in 2021 and is now on Version 98, approximately 1 major release every 2 weeks. Scroll has no official spec yet but creating a spec is on the roadmap.

This Tutorial will walk you through most parsers in Scroll AND teach you how to build your own Scroll Parsers.

A Scroll document

A Scroll document (or "program") is a list of nodes. Every node is one line and every line is one node.

If you put a space at the beginning of a line, that line becomes a child of the preceding line. You have probably seen this indent trick before in languages like Python. But Scroll pushes it to the max.

If you master the indent trick, you master Scroll. But we're getting ahead of ourselves, let's start with the basics.

Basic Node Types

1. The Paragraph Parser

Let's start with the most common parser, the paragraph parser. You can think of paragraphs as similar to a p or div tag in HTML. To use this parser you can write out the word paragraph, or use an asterisk *, OR just start any text that does not match another parser (the "catch all" parser of a Scroll program is the paragraph parser). This paragraph you are reading was compiled by a paragraph parser. The code is:

Let's start with the most common parser, the `paragraph` parser. You can think of paragraphs as similar to a `p` or `div` tag in HTML. To use this parser you can write out the word `paragraph`, or use an asterisk `*`, OR just start any text that does not match another parser (the "catch all" parser of a Scroll program is the paragraph parser). This paragraph you are reading was compiled by a paragraph parser. The code is:

2. Headers

Scroll has headers like markdown:

# This is a section header
## This is a subsection header

This is a section header

This is a subsection header

3. Unordered lists

Here's how you write unordered lists:

- Scroll has lists
 - That can be nested

Scroll has lists

That can be nested

4. Checklists

Below is the code for a checklist and its rendered version:

[] Finish full tutorial
 [x] Learn that checklists support nesting

Finish full tutorial

Learn that checklists support nesting

5. Tables

Use the table parser and include your delimiter for tables:

table ,
 Name,Rank
 Scroll,#1
 Markdown,#2

Name	Rank
Scroll	#1
Markdown	#2

6. Images

To add an image use the image parser:

image https://scroll.pub/blog/screenshot.png
 caption An image with a caption

7. Footnotes

You can make footnotes like this:

Pau means done^pau
^pau In Hawaiian

Pau means done^[1]

[1] In Hawaiian

8. Dashboard

If you are building a dashboard you might want to try the dashboard parser:

dashboard
 #1 Lang
 2k Users
 300 Stars

#1Lang

2kUsers

300Stars

9. Including HTML and CSS

If you need to jump into regular HTML, use the html parser. html If you need to jump into regular HTML, use the <code>html</code> parser.

For CSS, use the css parser:

css .green {color: green;}
This text should be green.
 class green

This text should be green.

Marking Up Text

Bold, italics and code

Formatting text is similar to Markdown or Textile.

Here's how to *bold*, _italicize_, or denote `code`.

Here's how to bold, italicize, or denote code.

Links

Scroll does links different. Instead of mixing in the link with the content, you put the link after the text along with the text you want the link to match against. For example:

A link to Wikipedia
 https://wikipedia.org Wikipedia

A link to Wikipedia

You can also make the whole paragraph a link by not including any text to match against.

A link to Wikipedia
 https://wikipedia.org

A link to Wikipedia

Columns

You can use the thinColumns [maxNumberOfColumns] parser to start a columns flow and endColumns to end a columns flow. If you don't want a section to break across columns, don't put line breaks in between lines. Line breaks will clear sections.

Advanced

Variables

Use the replace parser to define variables. Variables definitions are parsed and removed on the first compiler pass.

Our domain is: scroll.pub

Import statements

Scroll files can import other Scroll files. Use the import parser followed by the path to the file, such as: import header.scroll

Advanced: Custom Themes

A standard Scroll Theme consists of CSS and may also contain suggested pages and additional Parser extensions. The default scroll theme is called Gazette. The checklist below walks you through creating a complete Scroll Theme like Gazette.

Create a [yourThemeName].parsers file

Add a [yourThemeName]CssParser

You can refer to the gazetteCssParser in gazetteTheme.parsers for an example. Your theme can extend abstractThemeCssParser or be its own tag.

Add CSS. The Gazette theme uses Hakon, a language that compiles to CSS, but you are free to use plain CSS—even in an external file.

Add CSS resets. Like any other normal site you probably want to adjust the base CSS of the browser.

Add any custom styles for any custom parsers you include in your theme. If you don't have any custom parsers you can skip this step.

Add CSS for the standard Scroll parsers. You probably want to customize the styles of Scroll parsers like * and #. There is not currently an exhaustive list or consistent pattern to these class names. See the Gazette theme for reference.

Using Custom Themes

By default Scroll emits HTML with no theming. To use any theme—including the default Gazette theme—the user simply uses the parsers provided by the theme, such as gazetteCss.

Examples

A page using no theme:

# This page has no theme

A page using a theme:

gazetteCss
pageHeader
* This page uses the Gazette theme.
pageFooter

Expert: Adding your own parsers

Scroll is based on the theory that a language should adapt to the domain, not the other way around. So Scroll has extendibility built-in.

Note: Custom Parsers are currently only supported using the npm package. The web editor does not currently support custom parsers.

You can define your own parsers right in your Scroll documents using *Parser.

Here is a simple example that extends Scroll by making p work the same as *:

pParser
 extends paragraphParser
 crux p
p We can then make paragraphs using `p`.

We can then make paragraphs using p.

Let's now make a hiddenMessage Parser that alerts a message when clicked:

messageParser
 cruxFromId
 catchAllCellType stringCell
hiddenMessageParser
 extends paragraphParser
 inScope messageParser
 cruxFromId
 javascript
  compile() {
    return `<span onclick="alert('${this.get('message')}')">${super.compile()}</span>`
  }
hiddenMessage Click me.
 message Hello world

Click me.

As you can see, you can define new parsers with a small amount of code. You probably also can see that the Parsers code is powerful but has lots of sharp edges. While the documentation on Parsers evolves, feel free to get in touch for help in adding your own parsers.

Scroll Tutorial

Edit this in the Scroll Web Editor