schol

Academic writing made easy.

schol is a command line tool that makes it easy to write academic documents in Markdown and automatically manage and format citations.

Contents

• Why schol?
• System Requirements
• Installation
• Getting Started
• Features
  • Templates and Front Matter Metadata
  • Content
  • Citation Management
  • Citation Styles
• CLI Reference
• Contributors

Why schol?

• Mobile-accessible, web-first output by default
• Built-in citation management with automatic formatting for any citation style
• Cross-platform
• Easy and simple to install and use

System Requirements

• Node.js 8.12 or later
• Your favorite text editor (Sublime Text, Atom, VSCode, etc.)
• Your favorite terminal (CMD, PowerShell, Hyper, iTerm2, zsh, bash, etc.)
• A modern web browser (Chrome, Edge, Firefox, Opera, Safari, etc.)

Installation

To install schol, run the following in your terminal:

npm install -g schol

Getting Started

To start a new schol project, create a new folder for the project, navigate into it, and initialize the project with schol init:

mkdir assignment
cd assignment
schol init

Next, open the directory in your text editor. For example, if you're using Sublime Text:

subl .

You can then open src/index.md in your editor -- this is where you will save your work.

Next, start schol in edit mode:

schol edit

This will display your assignment in your web browser and automatically reload it whenever you save any changes. schol will continue to run in edit mode indefinitely until you stop it (Ctrl + W, closing the terminal, etc.). You might want to open a new terminal window to run other commands.

Make some changes to src/index.md in your editor and save them. Your browser will automatically reload with the latest changes.

Once you are finished your work, render the final output files:

schol render

This will save a copy of your finished work and all necessary files to the docs/ folder in your project directory. Distribute these files however you want -- for example, submit them for grading or review, or upload them to a website for publication.

To publish your work to [GitHub Pages free web hosting service]((https://pages.github.com/):

1. Create a new GitHub repository and push your project to it.
2. Set up your GitHub repository to publish from the docs/ folder in your project.

Your work is now published to the web!

Features

Templates and Front Matter Metadata

Every schol document has a template that determines how it is rendered. Specify your document template with the template property in your document:

template: ./my-assignment-template/

You can find a list of published templates on the wiki. If no template is specified, schol-template-default is used.

Templates embed document metadata like title and author details into their rendered output. Specify document metadata with a front matter section in your document:

title: The Impact of Bees on Hives
authors:
  - name:  John Smith
    email: [e-mail]
date: 2018-09-01
---

Different templates may require different front matter. For example, a template for a course assignment might require the following front matter:

assignment-name: Assignment 1
authors:
  - name: Your Name
    email: [e-mail]
course-number: COMP 101
course-name: Introduction to Computing
teacher: Dr. Maiga Chang
school: University of Liliput
date: 2018-08-31

The template would then render these values into a title section for your assignment.

Read the documentation for the template you are using to learn what metadata it requires.

Content

Author your content in CommonMark markdown immediately following the front matter of your document:

author: Jamie Czerwinski
---
 
# Introduction
 
Lorem ipsum...
 

schol parses your content with markdown-it and inserts it into your template for rendering.

Table of Contents

To include a Table of Contents within your document, insert ${toc} wherever you would like the table to appear.

Citation Management

schol appends your references to the end of your document, so remember to add a "References" or "Bibliography" header as the last line of your content:

...
 
# Conclusion
 
Lorem ipsum ... and more research is needed.
 
# References
 
*schol will append your references here*

To make a citation, use a bracketed caret symbol and citation label:

According to this citation,[^citation-label] ...

Make sure that each citation has a references entry in your document front matter:

references:
    citation-label: http://www.some-citation.com

Reference Format

A reference entry can be anything accepted by Citation.js, including any of the following:

• Digital Object Identifier (DOI)

  • 10.1109/5.771073

• DOI URL

  • https://doi.org/10.1109/5.771073

• Wikidata ID

  • Q24262882

• Wikidata URL

  • https://www.wikidata.org/wiki/Q24262882

• BibTeX string

  • @article{paskin1999toward,
      title={Toward unique identifiers},
      author={Paskin, Norman},
      journal={Proceedings of the IEEE},
      volume={87},
      number={7},
      pages={1208--1227},
      year={1999},
      publisher={IEEE}
    }
    

• BibJSON

  • {
      "title": "Toward unique identifiers",
      "type": "article",
      "author": [
        {
          "name": "Norman Paskin"
        }
      ],
      "journal": "Proceedings of the IEEE",
      "year": "1999",
      "volume": "87",
      "number": "7",
      "pages": "1208--1227"
    }
    

Citation Styles

You can specify the citation format to use in your document with a citation_style property in your document's front matter -- just specify the ID of any style in the Zotero Style Repository.

To get the ID of a style from the Zotero Style Repository, hover over any style in the list and click the "Link" link that appears to the right of the style's date. The ID will appear in the Style Search bar -- exclude the id: part:

citation_style: apa

If no citation_style is specified, schol defaults to apa.

CLI Reference

schol init [--template, -t template=schol-template-default]

Initializes a new schol project in the current directory.

Options

template: The schol template to initialize this project with.

schol edit

Opens your project in your web browser and watches for changes to the project. Automatically rebuilds the project and refreshes the browser when changes are detected. Does the same thing as schol render, but rebuilds the project as changes happen in real-time.

schol render

Generates a distributable and/or publishable version of your project in the docs/ folder.

Contributors

Jamie Czerwinski