Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[#247] Update site README with more detailed instructions #255

Merged
merged 1 commit into from
Mar 15, 2017
Merged

[#247] Update site README with more detailed instructions #255

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 40 additions & 6 deletions site/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,42 @@
# Microcosm Site

The Microcosm website draws from `../docs` and `./src/content` to
build pages. It is published to Github Pages here:
- [Introduction](#introduction)
- [Setup](#setup)
- [Run Locally](#run-locally)
- [Publish](#publish)

http://code.viget.com/microcosm/
## Introduction

The Microcosm website is built using markdown files, html templates, a stylesheet, and a few image assets. It is published using Github pages on the `gh-pages` branch. Check out the live site here: http://code.viget.com/microcosm/

> For more information on Gihub Pages got here: https://pages.github.com/.

Here is a brief overview of everything you'll find in the `site` folder:

### public

The generated site will live here after running (we'll go over generating the site and serving the site locally in the next section.) With the exception of the `assets` folder you should never edit these files, they will be overwritten when regenerating the site and aren't in source control.

### scripts

The `Makefile` uses these files to generate the html files in the `public` folder, to serve the site locally, and to publish the site to Github pages.

### src

The site is generated using the markdown files in `./src/pages` and the html templates in `.src/layouts` by Pandoc (see [setup section below](#setup)).

> Note that markdown files can also be found in `../docs` outside the site folder.

### Makefile

A [Makefile](https://en.wikipedia.org/wiki/Makefile) provides a few easy commands for building, serving, and publishing the site. To keep things simple there are two main ones you will most likely need:

- `make server` which lets you run the site locally on `localhost:4000`
- `make publish` which bundles the site, puts the files on the `gh-pages` branch, and pushes them to Github

## Setup

We use [pandoc](pandoc.org) to generate the site. This
needs to be installed. For OSX users:
We use [pandoc](pandoc.org) to generate the site. This needs to be installed. For OS X users:

```
brew install pandoc
Expand All @@ -23,11 +51,17 @@ cd site
make server
```

The html files will be generated (or updated) into `./public` and a server will be started running on `localhost:4000`. Point your browser there to see the site. Changes to files in `./src` or any `.md` file will trigger a live reload on the site (no need to hit refresh).

> To see what is going on under the hood look at the `Makefile` and at the `./scripts/serve` script. If you are not familiar with browser-sync check out [their website](https://www.browsersync.io/) for details.

## Publish

From the project root:
Publishing to `http://code.viget.com/microcosm` can only be done by core contributors with merging privileges. If this is you then publishing is straightforward, from the project root:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there other reasons to use the publish script? Contributors shouldn't submit PR's from the gh-pages branch right? We will generate the site ourselves when it's ready.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is correct. I don't think there is a reason for a non-managing contributor to use the publish script.


```
cd site
make publish
```

> To see what is going on under the hood look at the `Makefile` and at the `./scripts/publish` script. The script will force push the site to the `gh-pages` branch which will publish the site to `http://code.viget.com/microcosm`