import header.scroll
title 📜 Scroll: tools for thought.
startColumns
replace TreeNotationLinked <a href="https://treenotation.org">Tree Notation</a>
replace GrammarLinked <a href="https://jtree.treenotation.org/designer/#standard%20grammar">Grammar</a>
permalink index.html
keyboardNav releaseNotes.html releaseNotes.html

html
 <a href="https://github.com/breck7/scroll/actions/workflows/didTheTestsPass.yml"><img src="https://github.com/breck7/scroll/actions/workflows/didTheTestsPass.yml/badge.svg" style="width: 49%;"/></a> <a href="https://gitpod.io/#https://github.com/breck7/scroll"><img style="width: 49%;" src="https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod"/></a>

? Can you show me a screenshot?
image public/screenshot.png

? Can I try Scroll in the browser?
* Yes. Here is a web demo.
 https://try.scroll.pub/ web demo

? What has changed in recent versions?
* View the releaseNotes.
 link releaseNotes.html releaseNotes

? Is there an official blog for the project?
* Yes.
 link public/blog/ Yes

? Where is the NPM package?
* Here.
 link https://www.npmjs.com/package/scroll-cli

? Who is Scroll for?
* Scroll is built for developers who like writing, tools for thought, open source, git backed static site generators, and fast simple code.

? What makes Scroll different?
* Scroll is not just another static site generator but also a *new language*. More than just a new language. It's a _freakishly simple new language that you can extend in amazing ways_. Scroll is a high level language mostly written in a new lower level language called GrammarLinked, and both Grammar and Scroll are built on the new syntax called TreeNotationLinked.
 https://staticsitegenerators.net another static site generator
* The basics of Scroll are even simpler than Markdown. For example, the keyword for title is title.
 italics the keyword for title is title
* You can stick to the basics or easily define new keywords extending the language to better fit your content and workflows. A simple indent is all you need to include sublanguages. No complex encoding needed.

? How do I extend Scroll?
* 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
 
 * 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
* Notice that your post uses the keyword `recipe`, but Scroll does not have a keyword for that. No problem, just define it yourself using GrammarLinked, extending your dialect of Scroll:
code
 recipeNode
  extends abstractScrollNode
  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 mini-languages 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.
 link https://scroll.pub/public/blog/indented-heredocs.html one

? What is the biggest downside to Scroll?
* Althought it is simple to write GrammarLinked when you know what you're doing, documentation for GrammarLinked is still very poor and tooling isn't great yet. That will get better.

? What kind of sites can I use Scroll to build?
* 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.
 link https://scroll.pub one page
 link https://scroll.pub/public/blog/ a few pages
 link https://breckyunits.com/code/ tens of pages
 link https://breckyunits.com/ hundreds of pages
 link https://pldb.com/ thousands of pages

? How do I get Scroll?
* The instant way is to try Scroll in GitPod.
 link https://gitpod.io/#https://github.com/breck7/scroll GitPod
* 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
* 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.
 link https://www.npmjs.com/package/scroll-cli scroll-cli
* You can install from GitHub:
code
 git clone https://github.com/breck7/scroll
 cd scroll
 npm install -g .
* Or you can install Scroll with npm by typing:
code
 npm install -g scroll-cli

? How do I use Scroll?
* Scroll is a command line app. To see the commands type:
code
 scroll help

? Where do I get help?
* Post an issue in this GitHub or email us.
 email feedback@scroll.pub us

? What are some example sites using Scroll?
* Scroll currently powers blog and sites of one page, a few pages, tens of pages, hundreds of pages, and even thousands of pages.
 link https://scroll.pub one page
 link https://scroll.pub/public/blog/ a few pages
 link https://breckyunits.com/code/ tens of pages
 link https://breckyunits.com/ hundreds of pages
 link https://pldb.com/ thousands of pages

? What does a typical project folder look like?
* A typical Scroll project folder, excluding the files
 built by Scroll, looks like this:
code
 📁yourDomainName.org
  about.scroll
  firstPost.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`.
 
? How do I save drafts?
* Have a drafts folder next to your published scroll. For example:
code
 📁drafts
  someDraft.scroll
 📁yourDomainName.org
  publishedArticle.scroll

? What file formats does Scroll use?
* Scroll articles are written as Scroll files with the file
 extension scroll. The current base grammar for Scroll is defined here.
 code scroll
 https://github.com/breck7/scroll/tree/main/grammar here

? What language is Scroll written in?
* Scroll is mostly written in GrammarLinked. 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
* TypeScript is not used in the Scroll repo and because the Javascript is only ~1kloc that likely will not be necessary.

? How does versioning of articles work?
* Scroll is designed for git. A single article is stored as
 a single file tracked by git.

? Is Scroll public domain?
* Yes! Scroll is also 100% focused on helping people build internal or <strong>public domain sites</strong> and everything is designed with that assumption.

? Why does the default theme have a single page layout?
* 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.

? Will you make design decisions for non-public domain sites?
* No.

? Can I use Scroll for internal private sites not intended for publishing?
* Yes!

? In the single page layout why don't you have only the newest articles above the fold?
* 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.

? Is there a place I can play with the Scroll grammar?
* Yes. In the Tree Language Designer.
 https://jtree.treenotation.org/designer#url%20https%3A%2F%2Ftry.scroll.pub%2FscrollScript.grammar Tree Language Designer

? What's an easy way to have GitHub run Scroll and build my HTML files automatically?
* Go to your project folder and create the file below:
code
 mkdir -p .github/workflows
 touch .github/workflows/buildAndDeployScroll.yaml
* 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/checkout@v2.3.1
       - 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/github-pages-deploy-action@4.1.4
         with:
           branch: scroll-output # 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 scroll-output branch as the Source for the pages. Click save. Your built site should be live.
 code Settings
 code Pages
 code scroll-output

? How do I check for broken links?
* 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

? How do I check browser performance?
* 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

? Where should I host my site?
* 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

? How do I use Scroll with a custom domain?
* 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

? How can I deploy my site?
* 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
* 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

? How can I output my Scroll to an EPUB file?
* 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

? How can I track web traffic?
* 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

? Does Scroll support RSS?
* Yes! Just create a `feed.scroll` file like this.
 https://github.com/breck7/scroll/blob/main/public/blog/feed.scroll this

? Does Scroll support categories and category pages?
* Yes! Just add your page to a category by using the `groups` keyword and then creating a `yourGroupName.scroll` page for the group. See a demo here.
 https://github.com/breck7/scroll/blob/main/public/blog/ here

? Does Scroll support Open Graph tags for better social media sharing?
* 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 Twitter.
 https://developers.facebook.com/tools/debug Facebook
 https://cards-dev.twitter.com/validator Twitter

? Does Scroll support themes and templates?
* 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.

? How can I build a scroll from a Twitter account?
* 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

? What were some alternatives considered?
* There was no publishing software that reads and writes Scroll 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

# Contributing to Scroll development
? How do I contribute?
* File issues. Share your Scroll sites.
* You can submit pull requests too. The shorter the better.

? 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

? How is a keyword different than a web components?
* Scroll 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 targetting 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.

? How do I run cross browser tests?
* For that we use BrowserStack.
 link https://browserstack.com BrowserStack

? Why the name Scroll?
* 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.

endColumns
import footer.scroll