Have a question not answered here? Email feedback@scroll.pub.
Scroll powers an ever increasing number of blogs like this one.
Scroll powers PLDB, a knowledge base with over 100 contributors who have added over 100,000 atoms of structured data and thousands of pages.
This site you are reading is powered by Scroll.
Scroll has an unusually simple syntax called Particles, an extensive set of parsers and commands needed by researchers, bloggers, knowledge bases and sites of all sizes, is highly expandable, and is familiar to anyone who knows Markdown.
The command line app builds static blogs, websites, CSVs, text files, and more.
Scroll currently requires Node.js.
After Node.js is installed, install the npm package with:
npm install -g scroll-cli
git clone https://github.com/breck7/scroll.git
cd scroll
npm install -g .
npm test
scroll help
Yes. Breck's Lab publishes Scroll to the public domain.
The source code is hosted on GitHub.
Yes.
Scroll is built for bloggers who appreciate writing, minimal, well designed tools for thoughts, open source, git backed static site generators, and fast simple code.
Scroll is different than other static site generators because it is also an extendible language.
The basics of Scroll are even simpler than Markdown. For example, you can make a whole paragraph a link like this:
This is a link
https://scroll.pub
You can stick to the basics or define new parsers to extend Scroll to better fit your content and workflows.
Your parsers can be simple or as complex as any programming language, and a simple indent is all you need to make sure your parser won't interfere with other parsers.
Parsers in Scroll are written in a mini language called Parsers and both Scroll and Parsers are built on the syntax called Particles.
Scroll evolved based on the theory that instead of a fixed language for blogging it is better to have an ever evolving ecosystem of parsers, so that your symbolic tools can grow along with your mental tools.
Thus, Scroll is designed to be easy to extend.
You can see this in the Scroll source code.
Scroll is a collection of Parsers and there are currently dozens of .parsers
files in the base distribution.
Each Parser can define a mini language of its own. You can simply add (or remove) Parsers to generate your own custom dialects to better fit your domains.
Think of it as one file, many languages.
Altering traditional languages in this fashion would lead to chaos, but Scroll does it in a stable and scalable way by making the most of the indent trick (also known as the off-side rule). Each line gets its own scope. So you can add, remove, and update your microlanguages and their associated blocks without breaking the rest of the documents.
In Scroll, it's almost as if each line is its own file.
Imagine you run a cooking blog where you share recipes. It may be useful to present recipes to your readers in a specialized style. You could create a recipe parser and write a post like this:
# McCarthy Salad
https://www.dorchestercollection.com/the-edit/los-angeles/our-famous-mccarthy-salad-recipe
recipe
ingredients For salad
¼ head iceberg lettuce
½ head romaine lettuce
½ cup diced, grilled free-range chicken
½ cup diced, roasted red beets
¼ cup free-range egg yolk
¼ cup free-range egg white
½ cup finely diced aged cheddar cheese
½ cup applewood-smoked bacon
¼ cup diced tomato
¼ cup diced avocado
step Dice ingredients.
step Artfully arrange the salad ingredients in a bowl.
ingredients For salad dressing
1 cup balsamic vinegar
1 shallot
3 cloves roasted garlic
1 teaspoon Dijon mustard
Salt and black pepper to season
Canola oil
step Place the dressing ingredients in a blender and drizzle in the canola oil to emulsify.
step Combine and mix salad and dressing!
step Enjoy!
Notice that your post uses the first atom recipe
, but Scroll does not have a parser for that. No problem, just write a recipe parser yourself using Parsers, extending your dialect of Scroll:
recipeParser
extends abstractScrollParser
crux recipe
javascript
compile() {
const addYourSpecialMagic = ""
return `<div>${addYourSpecialMagic}</div>`
}
Your extension might generate beautiful custom HTML for that recipe section and also perhaps allow users to vote on it, or include it in a CSV export, et cetera. Scroll let's you combine microlanguages in a simple and non-conflicting way. What you do with those languages is up to you.
For an extended example of extending Scroll check out this one which adds node types for Markdown, Textile, and BBCode.
Compared to Markdown there is very little tooling and the ecosystem is currently very small.
Also, although it is simple to write your own parsers in Parsers once you know what you're doing, documentation for Parsers is still poor and tooling isn't great yet.
Scroll is a great solution for blogs and sites of one page, a few pages, tens of pages, hundreds of pages, or even thousands of pages.
Scroll is a language and command line app you install on your local machine. Scroll requires basic familiarity with the command line and NodeJs >=18. If you do not have NodeJs, Mac/Linux users can install NodeJs with --arch arm64
flag for M1s+) and Windows users can install NodeJs with Scoop.
If you would like to use Scroll but aren't familiar with the command line, please open an issue and we may be able to help.
Once you have NodeJs installed you can install from GitHub or npm. Scroll is scroll-cli on npm.
You can install from GitHub:
git clone https://github.com/breck7/scroll
cd scroll
npm install -g .
Or you can install Scroll with npm by typing:
npm install -g scroll-cli --production
One way to try the Scroll command line app without installing is with GitPod.
Scroll is a command line app. To see the commands type:
scroll help
Post an issue in this GitHub or email us.
Scroll currently powers blog and sites of one page, a few pages, tens of pages, hundreds of pages, and even thousands of pages.
A typical Scroll project folder, excluding the files built by Scroll, looks like this:
📁yourDomainName.org
about.scroll
helloWorld.scroll
index.scroll
header.scroll
footer.scroll
anImageInTheArticle.png
When you run scroll build
, Scroll reads those files and generates the outputs right in that site's folder.
With Scroll your site's Scroll files and static files and generated html are all in one public folder and checked into version control. Usually you want to add *.html
and feed.xml
to your .gitignore
.
Have a drafts folder next to your published scroll. For example:
📁drafts
someDraft.scroll
📁yourDomainName.org
publishedArticle.scroll
Scroll articles are written as Scroll files with the file extension scroll
. The current base parsers for Scroll are defined here.
Scroll is written in Particles, Parsers, and Javascript. The Scroll CLI app is written in plain Javascript and runs in Node.js. Scroll also uses a few other microlangs written in Parsers. The CSS for the default theme Gazette is written in Hakon. The HTML is written in stump.
TypeScript is not used in the Scroll repo and because the Javascript is only ~1kloc that likely will not be necessary.
Scroll is designed for git. A single article is stored as a single file tracked by git.
Yes! Scroll is also 100% focused on helping people build internal or public domain sites and everything is designed with that assumption.
The default Scroll theme is designed to make it easier for syntopic reading. Being able to scan the page like a newspaper. This allows you to read at a higher level—to "get in the author's head"—compared to reading one article at a time from beginning to end.
And if anyone prefers to read a scroll in a different way—they can! Scroll is for public domain sites. People are free to arrange the symbols any way they wish.
No.
Yes!
This was originally a bug. But then it turns out to be a feature, as it gives older articles, which are often more important, more visibility.
scroll list | scroll build
Go to your project folder and create the file below:
mkdir -p .github/workflows
touch .github/workflows/wws.yaml
Then open that file and paste in this code:
# Adapted from https://github.com/JamesIves/github-pages-deploy-action
name: Build and Deploy Scroll
on:
push:
branches:
- main
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout 🛎️
uses: actions/checkout@v2.3.1
- name: Install and Build
run: |
npm install -g scroll-cli --production
scroll build
# The line below is needed if you have *.html in your gitignore file
rm .gitignore
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@4.1.4
with:
branch: wws # The branch the action should deploy to.
folder: .
Commit and push. Now go to your GitHub Repo and then Settings
, then Pages
, and select the wws
branch as the Source for the pages. Click save. Your built site should be live.
Check out the 404.scroll
file in this folder.
GitHub has instructions but is really is as simple as this:
Scroll does not check for broken links. For that, try linkinator.
# npm install -g linkinator
linkinator https://scroll.pub > brokenLinks.txt
Scroll does not have browser perf tools built in. For that, try lighthouse.
# npm install -g lighthouse
lighthouse https://scroll.pub --output-path scrollBrowserPerf.html; open scrollBrowserPerf.html
Any web server works. You can even host your scroll for free using GitHub Pages, just like this site.
Just buy a domain and point it to your web server or web host (such as GitHub Pages). Google Domains is where this domain is registered and is a great service.
If you have your own web server try rsync. Here's a bash one liner:
# deploy.sh
# swap "/var/www/html" with the path to your website's location on your web server
rsync -vr /[path/to/your/site]/* [yourdomain.com]:/var/www/html
Add a section like the one below to your ~.ssh/config to save your username and correct key pair.
Host example.com
User yourUserName
IdentityFile ~/.ssh/example_id_rsa
IdentitiesOnly yes
Yes! Support for plain text outputs as added in April, 2024.
Pandoc is one way to do it. If you are on a Mac and have Homebrew installed:
brew install pandoc
pandoc index.html -o book.epub
Scroll does not come with hot reloading but you can easily set it up with nodemon
. Install nodemon
with sudo npm install -g nodemon
. Then run:
nodemon -e scroll -x "scroll build"
Or alias it:
alias watch="nodemon -e scroll -x 'scroll build'"
You can also add the following code to the page(s) you are working on to have them reload without manually refreshing the browser:
html <meta http-equiv="refresh" content="1;">
Scroll emits HTML with zero Javascript and does not have any tracking or cookies. You can easily add your own tracking tag if you want.
If you are self hosting using a web server like Nginx you might have some access logs on your server. The one liner below uses GoAccess to summarize recent Nginx access logs.
# apt-get install goaccess
goaccess /var/log/nginx/access.log -o /var/www/html/YOUR_SECRET_REPORT_URL.html --log-format=COMBINED --real-time-html --ws-url=wss://YOURDOMAIN.com
Yes! Just create a feed.scroll
file like this.
Yes! Add tags to a post using the tags
parser. Then create a yourTagName.scroll
file to create a category page for that tag. See a demo here.
Yes. By default the first image and first paragraph of an article will be used for the "og:" tags. Unfortunately Twitter doesn't support relative image links so you need to specify baseUrl
. For more help check out the debuggers from Facebook and X or try LinkPreview.
Yes! Scroll includes a simple API for changing the style of your site. This is an active area of development so please reach out if you'd like to customize the look of your Scroll.
Hopefully someone will build a package or site that does this. For now, on your Twitter settings, download an archive of your data and convert the tweets JSON into scroll files. Or to experiment faster use this tool to grab some tweets as a TSV.
There was no publishing software that reads and writes Scroll yet so building Scroll was necessary. Jekyll and Brecksblog were the two biggest inspirations.
File issues. Share your Scroll sites.
You can submit pull requests too. The shorter the better.
# cd your_slow_scroll
# you may need to update the path below so it points to your scroll code
node --cpu-prof --cpu-prof-name=scrollNodePerf.cpuprofile ~/scroll/scroll.js build
# Now ➡️ open a new Chrome tab ➡️ open devtools ➡️ click Performance ➡️ click "Load Profile..." ➡️ select your scrollNodePerf.cpuprofile
# For profiling memory, use this line:
node --cpu-prof --cpu-prof-name=scrollNodePerf.cpuprofile --heap-prof --heap-prof-name=scrollNodeMem.heapprofile ~/scroll/scroll.js build
# Now ➡️ open a new Chrome tab ➡️ open devtools ➡️ click Memory ➡️ click "Load Profile..." ➡️ select your scrollNodeMem.heapprofile
Scroll Parsers and Web Components are similar in that both empower users to define their own reusable components. But Scroll is higher level than web components. For example, in addition to easily targeting HTML and web components, Scroll also plays really nicely with version control and 2D editors. Scroll encourages encoding semantic content with as little noise as possible, which creates benefits in many places.
For that we use BrowserStack.
Each Scroll file is currently passed over 4 times during compilation to HTML and/or text.
import
statements are replaced with the contents of the imported file.replace
statements are executed and applied to the current file.The scroll was invented thousands of years ago and scrolls are still useful today. Scroll has been designed with a focus on simplicity and a goal of making something that would have been useful decades ago, with the hope that this will make it useful decades into the future.