title 📜 Scroll: an extensible alternative to Markdown. permalink index.html

html

question Can you show me a screenshot?

image public/screenshot.png

question Can I try Scroll in the browser?

aftertext Yes. Here is a web demo. https://try.scroll.pub/ web demo

question What makes Scroll different?

aftertext Scroll is different than other static site generators because it uses the easily extendible ScrollScript, so you can invent new languages to better fit your content. bold ScrollScript https://staticsitegenerators.net other static site generators

aftertext The basics of ScrollScript are even simpler than Markdown. For example, the keyword for title is title. italics the keyword for title is title

aftertext You can stick to the basics or easily define new keywords to better fit your content and workflows. A simple indent is all you need to include sublanguages. No complex encoding needed.

question How do I extend Scroll?

aftertext 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 keyword and write a post like this: italics recipe

code title My Snowball Cookies

paragraph Bet you can't eat just one!

recipe ingredients 6 large eggs 1/2 cup sugar step Beat eggs until foamy step Add sugar step Heat oven to 350 degrees step Bake for 10 minutes

aftertext Your grammar 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. ScrollScript let's you combine mini-languages in a simple and non-conflicting way. What you do with those languages is up to you.

aftertext (Warning: the cookies above have not been tasted)

aftertext For an extended example of extending Scroll check out this one which adds node types for Markdown, Textile, and BBCode. link https://github.com/breck7/breckyunits.com/tree/main/markups one

question What kind of sites can I use Scroll to build?

aftertext Scroll work great for blogs, collaborative databases, newspapers, intranets and other types of static sites as well.

question How do I get Scroll?

aftertext The instant way is to try Scroll in GitPod. link https://gitpod.io/#https://github.com/breck7/scroll GitPod

aftertext Scroll is a command line app you install on your local machine. Scroll requires basic familiarity with the command line and NodeJs >=14. If you do not have NodeJs, Mac/Linux users can install NodeJs with #n# and Windows users can install NodeJs with Scoop. link https://nodejs.org NodeJs wrap # https://github.com/tj/n https://scoop.sh/ Scoop

aftertext 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.

aftertext Once you have NodeJs installed you can install from GitHub or npm. Scroll is scroll-cli on npm. link https://www.npmjs.com/package/scroll-cli scroll-cli

aftertext You can install from GitHub:

code git clone https://github.com/breck7/scroll cd scroll npm install -g .

aftertext Or you can install Scroll with npm by typing:

code npm install -g scroll-cli

question How do I use Scroll?

aftertext Scroll is a command line app. To see the commands type:

code scroll help

question Where do I get help?

aftertext Post an issue in this GitHub or email us. email [email protected] us

question What are some example sites using Scroll?

aftertext This page, BreckYunits.com and TreeDB. link https://breckyunits.com BreckYunits.com link https://treebase.treenotation.org/treedb/ TreeDB

question What does the name Scroll refer to?

aftertext A scroll is a single folder containing ScrollScript files ending in .scroll and an optional scroll.settings file. Scroll compiles those ScrollScript files into a static index.html page. wrapsOn

aftertext Scroll is also the name of the command line app that includes a simple fs watch app for live preview.

aftertext ScrollScript is the name of a Tree Language defined in this grammar. link https://github.com/breck7/scroll/tree/main/grammar grammar

question What does a typical project folder look like?

aftertext A typical Scroll project folder, excluding the html files built by Scroll, looks like this:

code 📁yourDomainName.org about.scroll publishedArticle.scroll anImageInTheArticle.png scroll.settings

aftertext When you build a Scroll site, you are simply generating the index.html and [article].html files in the site's folder. code index.html code [article].html

aftertext 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 to your .gitignore. code *.html code .gitignore

question How do I save drafts?

aftertext Have a draft scroll next to your published scroll. For example:

code 📁drafts someDraft.scroll 📁yourDomainName.org publishedArticle.scroll

question What file formats does Scroll use?

aftertext Scroll articles are written as ScrollScript files with the file extension scroll. The current base grammar for ScrollScript is defined here. code scroll https://github.com/breck7/scroll/tree/main/grammar here

question What language is Scroll written in?

aftertext The Scroll CLI app is written in plain Javascript and runs in Node.js. Scroll makes heavy use of Tree Languages. The CSS is written in Hakon. The HTML is written in stump. link https://jtree.treenotation.org/designer/#standard%20hakon Hakon link https://jtree.treenotation.org/designer/#standard%20stump stump

aftertext TypeScript may be used in the future but Scroll may never get over 1kloc so that might not be necessary.

question How does versioning of articles work?

aftertext Scroll is designed for git. A single article is stored as a single file tracked by git.

question Is Scroll public domain?

aftertext Yes! Scroll is also 100% focused on helping people build internal or public domain sites and everything is designed with that assumption.

question Why does the default theme have a single page layout?

aftertext 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. bold syntopic reading

aftertext 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.

question Will you make design decisions for non-public domain sites?

aftertext No.

question Can I use Scroll for internal private sites not intended for publishing?

aftertext Yes!

question In the single page layout why don't you have only the newest articles above the fold?

aftertext 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.

question Is there a place I can play with the ScrollScript grammar and see how it compiles to HTML?

aftertext Yes. In the Tree Language Designer. https://jtree.treenotation.org/designer#url%20https%3A%2F%2Ftry.scroll.pub%2FscrollScript.grammar Tree Language Designer

question What's an easy way to have GitHub run Scroll and build my HTML files automatically?

aftertext Go to your project folder and create the file below:

code mkdir -p .github/workflows touch .github/workflows/buildAndDeployScroll.yaml

aftertext Then open that file and paste in this code:

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/[email protected] - name: Install and Build run: | npm install scroll-cli ./node_modules/scroll-cli/scroll.js build # Uncomment the line below if you are ignoring *.html files in your gitignore file # rm .gitignore - name: Deploy 🚀 uses: JamesIves/[email protected] with: branch: scroll-output # The branch the action should deploy to. folder: .

aftertext Commit and push. Now go to your GitHub Repo and then Settings, then Pages, and select the scroll-output branch as the Source for the pages. Click save. Your built site should be live. code Settings code Pages code scroll-output

question How do I check for broken links?

aftertext Scroll does not check for broken links. For that, try linkinator. link https://github.com/JustinBeckwith/linkinator linkinator

code

npm install -g linkinator

linkinator https://scroll.pub > brokenLinks.txt

question How do I check browser performance?

aftertext Scroll does not have browser perf tools built in. For that, try lighthouse. link https://github.com/GoogleChrome/lighthouse lighthouse

code

npm install -g lighthouse

lighthouse https://scroll.pub --output-path scrollBrowserPerf.html; open scrollBrowserPerf.html

question Where should I host my site?

aftertext Any web server works. You can even host your scroll for free using GitHub Pages, just like this site. https://pages.github.com GitHub Pages

question How do I use Scroll with a custom domain?

aftertext 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. https://domains.google Google Domains

question How can I deploy my site?

aftertext If you have your own web server try rsync. Here's a bash one liner:

code

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

aftertext Add a section like the one below to your ~.ssh/config to save your username and correct key pair. link https://unix.stackexchange.com/questions/494483/specifying-an-identityfile-with-ssh section

code Host example.com User yourUserName IdentityFile ~/.ssh/example_id_rsa IdentitiesOnly yes

question How can I output my Scroll to an EPUB file?

aftertext Pandoc is one way to do it. If you are on a Mac and have Homebrew installed: link https://brew.sh Homebrew

code brew install pandoc pandoc index.html -o book.epub

question How can I track web traffic?

aftertext Scroll emits HTML with zero Javascript and does not have any tracking or cookies. If you are 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. link https://goaccess.io GoAccess

code

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

question Does Scroll support Open Graph tags for better social media sharing?

aftertext 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 in your scroll.settings file. For more help check out the debuggers from Facebook and Twitter. code baseUrl code scroll.settings https://developers.facebook.com/tools/debug Facebook https://cards-dev.twitter.com/validator Twitter

question Does Scroll support themes?

aftertext 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.

question How can I build a scroll from a Twitter account?

aftertext 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. link https://www.vicinitas.io/free-tools/download-user-tweets tool

question What were some alternatives considered?

aftertext There was no publishing software that reads and writes ScrollScript yet so building Scroll was necessary. Jekyll and Brecksblog were the two biggest inspirations. link https://jekyllrb.com Jekyll link https://github.com/breck7/brecksblog Brecksblog

question What has changed in recent versions?

aftertext View the releaseNotes. link releaseNotes.html releaseNotes

section Contributing to Scroll development

question How do I contribute?

aftertext File issues. Share your Scroll sites.

aftertext You can submit pull requests too. The shorter the better.

question How do I debug node.js performance?

code

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

question How is a keyword different than a web components?

aftertext ScrollScript and Web Components are similar in that both empower users to define their own reusable components. But ScrollScript is higher level than web components. For example, in addition to easily targetting HTML and web components, ScrollScript also plays really nicely with version control and 2D editors. ScrollScript encourages encoding semantic content with as little noise as possible, which creates benefits in many places.

question How do I run cross browser tests?

aftertext For that we use BrowserStack. link https://browserstack.com BrowserStack