Skip to content

Latest commit

 

History

History
134 lines (95 loc) · 5.1 KB

manual.md

File metadata and controls

134 lines (95 loc) · 5.1 KB
Raw
layout title editor toc repository
page
Manual
admin
background
write
review
publish

This manual is based on a documentation written by Alex Gil with beginners in mind, but has the necessary information for more seasoned conspirators. We will walk through writing a sample blog post titled The Twisted Cubic.

Background

The {{ site.title }} is backed by Jekyll, the static site generator, and uses the minimal Ed theme and $$\KaTeX$$ for displaying math. The content of the site is hosted on its own GitHub [repository]({{ page.repository }}), so in order to collude you will need a GitHub account. While this process is a bit more involved than Wordpress and other similar tools, the payoff in the long term is worth the effort to learn it.

Write!

Each blog post is written in Markdown and is stored in the [_posts]({{ page.repository }}/tree/master/_posts) directory on GitHub. If you are familiar with $$\LaTeX$$ then learning Markdown will be a piece of cake; just open your favorite plain-text editor and start with the front matter:

---
layout: post
title: The Twisted Cubic
author: David Hilbert
categories: ["algebraic geometry", "examples"]
date: 1900-01-01
---

Typically, an easy way to write a new entry is to copy an existing one, replace the content and rename the file. Referring to older entries to remember how to add blockquotes, bibliographies, tables, etc. is also very helpful. Here we go over a few common styling formats:

# Section 1

## Subsection 1.1
You can write stuff in _italics_, **bold**, or even ~~strikethrough~~.

Next paragraph should start like this. Do not indent.

You can use $$ .. $$ to write mathematical formulas:

The function $$\nu$$ is written inline, but can also be in a block:

$$ \nu: \mathbb{P}^{1} \to \mathbb{P}^{3} $$

To add footnotes, use the following format:

- O Captain! my Captain! rise up and hear the bells;
- Rise up—for you the flag is flung—for you the bugle[^fn1] trills,

[^fn1]:
	The bugle is a small trumpet implicated in the military industrial complex.

Looks about ready to submit, so save the file as the-twisted-cubic.md to match the title. We will have many chances to perfect it later.

There are two routes for submitting a post:

Simple

This option is useful if you don't need anything beyond basic Markdown:

  • open [_posts]({{ page.repository }}/tree/master/_posts)
  • click [upload file]({{ page.repository }}/upload/master/_posts)
  • upload the-twisted-cubic.md
  • write a commit title, e.g. New Entry: The Twisted Cubic
  • choose "Create a new branch for this commit and start a pull request"
  • write post/the-twisted-cubic as the branch name
  • click "Propose new file"

This process creates a new [pull request]({{ page.repository }}/pulls), which allows you to keep working on the post.

Advanced

This method is useful for more involved posts, and a working knowledge of your operating system's terminal is assumed.

First, follow the guide for your operating system here to install a Ruby on your computer. Then, using the terminal's cd command, switch to the directory where you want to have your writing environment. Once inside the folder, enter the following commands:

$ git clone {{ page.repository }}.git proof
$ cd proof
$ make install

If everything works without an error, you can now build a local version of the site by entering:

$ make serve

If the site was rendered fine, copy the url from your terminal log and paste it into your browser. This url usually looks something like http://127.0.0.1:4000/proof/. At this point you should be looking at your very own working version of the {{ site.title }}.

Once the writing environment is set up:

$ git checkout -b post/the-twisted-cubic
$ git add _posts/the-twisted-cubic.md
$ git commit -m "New Entry: The Twisted Cubic"
$ git push origin
  • open [this page]({{ page.repository }}/compare/master...master) in a browser
  • change the second drop down menu to compare: post/the-twisted-cubic
  • make a new pull request

Review

FIXME

Publish

FIXME

If you would like to learn more, use these references to learn more about: Ed, basic Markdown, GitHub Pages, or Jekyll.

Happy colluding!