PlainSite

PlainSite is a simple but powerful static site generator inspired by Jekyll and Octopress.


Keywords
jekyll, octopress, ruby, static-site-generator
License
MIT
Install
gem install PlainSite -v 1.0.0

Documentation

PlainSite

A Simple but Powerful Static Site Generator Inspired by Jekyll and Octopress.

Getting Started

  1. Install gem:
gem install plain_site
  1. Init site:
cd mysite
plainsite init
  1. Create new post:
plainsite newpost post-slug 'Hello,wolrd!This is the title!'
  1. Preview site,open http://localhost:1990/ in your web browser.
plainsite serve
  1. Configure '_src/config.yml'

    url: http://example.com   # You site's domain or url prefix.
    disqus_id:                # Config to enable disqus comments.
    name: YouBlogName
    author: YouName
  2. Build site static pages:

plainsite build

Features

  1. Give you back full control of generating pages.
  2. Along with Git,PlainSite can only generate updated posts' corresponding pages.
  3. LazyLoad. It won't make your hard disk turn madly.
  4. Build in a live reload preview web server.
  5. Generate relative url optionally. So you can view you site through file:// protocal without any web server.
  6. Auto clean deleted post's corresponding pages.
  7. Pagination becomes incrediblely simple.

Site Directory Structrue

Run plainsite init will get things done.

.
├── .git
├── .nojekyll
└── _src
  ├── assets
  ├── data
  │   ├── category
  │   ├── demo-post.html
  │   └── 2012-12-25-hello-world.md
  ├── templates
  │   └── post.html
  ├── routes.rb
  └── config.yml

All files under _src directory are the source files.Here is each sub directory's usage:

  1. assets: Put all your static files in it for easier maintemance.When building,PlainSite will copy them to site's root.For example,you want to add a CNAME file to enable custom domain,you need to put it at /_src/assets/CNAME,so PlainSite will copy it to /CNAME.
  2. data: Put your post files here,each file corresponds to a Post,each directory corresponds to a Category.
  3. templates: ERB template files.
  4. routes.rb: All custom tricks:url pattern,pagination...
  5. config.yml: Site configurations.

Command Usages

  1. Run plainsite build --local will use relative url in output pages.
  2. Run plainsite build --all will force generate all pages.
  3. Run plainsite help for more command line options.

Code Highlight

Example post file content:

---
title: Hello,world!
---

**Here is post's content!**

Ruby:
<highlight ruby>
puts "Hello,world!"
</highlight>

Python,with line numbers:
<highlight python linenos>
def hello():
  print("Hello")
</highlight>

Specify the start line number,and PHP code did not need a "<?php" header:
<highlight php linenos=20>
echo "PlainSite";
ob_flush();
</highlight>

If there is no line feed char in code,
it will output an inline code element:<highlight>puts "Inline"</highlight>

Customation

Concepts:

  1. Post:PlainSite::Data::Post

Plain text file under _src/data/,represents one post.

  1. Category:PlainSite::Data::Category

    Directory under _src/data/.

  2. Template

    ERB template files Under _src/templates/ directory.

  3. Routes

    Ruby script at _src/routes.rb.

PlainSite will ignore Post、Template files or Category directories which prefix with underscore.

Post and Category

Files under site's _src/data/ directory represent Post:

_src/data/2011-02-28-hello-world.md

The 2011-02-28 is post's created date(optional);hello-world is post's slug(required).It's not allowed that two post files under the same category directory have the same slug;The .md ,viz. extname,represents Post's content type(PlainSite only support Markdown and HTML two content types,corresponding extnames are md and html.

Post file content must start with YAML-Front format header,and at least contains a title property.

The Post file's path relative to _src/data represents its Category.You can use directory as category to organize posts.For example,here are two categories:programming and essays:

_src/data/programming/2011-02-28-hello-world.md
_src/data/essays/2013-04-22-life-is-a-game.md

Category.data_id is the path relative to _src/data.

Post.data_id = Post.category.data_id / Post.slug

You can put an _meta.yml file under Category's directory to custom its attributes,such as display_name: Here is an example file at _src/data/programming/_meta.yml

display_name: ProgrammingLife

All properties specified in post's YAML header can be accessed via Post object directly.

Routes and Templates

File _src/routes.rb can be used to custom url pattern and all what you want. The _src/routes.rb file is just a Ruby script that loaded and executed by PlainSite. You can use global variable $site to access current PlainSite::Site instance object. Through $site.data to get site root category(_src/data),PlainSite::Data::Category instance object. For examples:

# coding:utf-8

$site.route(
  # url_pattern specify the output page's urlpath(relative to site root)
  url_pattern: 'index.html',

  # template file path relative to `_src/templates/`
  template: 'index.html',

  # The 'data' will be sent to template to render,if data is Array/PostList object,
  # It will render each item with template to output each page.
  # ERB template's context is which 'data' property specified,
  # ERB code can access its key or method directly,
  # e.g. here 'index.html' template's erb code can directly use site and demo variables
  data: {site: $site, demo:123},
  build_anyway:true # Force build this route every time.
)

$site.route( # Generate single post page
  url_pattern: 'about.html',
  data: $site.data / :about , # Retrieve the Post which data_id is 'about'
  template: 'post.html'
)

$site.route( # Generate posts under essays category
  # ur_pattern: '{date.year}/{date.month}/{date.day}/{slug}.html',
  url_pattern: '{data_id}.html', # url_pattern support variable replacement
                                 # which is Post's property
  data: 'essays/*', # Ge all posts under 'essays',return PlainSite::Data::PostList instance
  template: 'post.html'
)

$site.route(
  url_pattern: 'programming/{slug}.html',
  data: $site.data / :programming / :*, # can be also written as  'programming/*'
  template: 'post.html'
)

# $site.data.subs are categories under '_src/data',return Category[]
$site.data.subs.each do |category|
  $site.route(
    url_pattern: "#{category.name}/{slug}.html",
    # category.posts/5 means category.paginate(page_size:5),return PostListPage[]
    data: category.posts/5 , # category.posts is same as 'category / :* '
    template: 'list.html'
  )
end

Template system supports layout,specified in its YAML Header:

---
layout: base.html   # file path relative to self
---
<% content_for :page_title do %>
  <%=title%> - <%=site.name %>
<% end %>
<% content_for :page_content do %>
  <h1><%=title%></h1>
  <p>Date:<%=date%></p>
  <%=content%>
  <hr />

  Use site.url_for to get url,so it can be affected by 'plainsite build --local',results in relative url.
  <%=site.url_for 'essays/hello' %>

  Also support includes.
  <%=include 'footer.html' %>
<% end %>

The base.html contents:

<html>
<head>
  <title><%=yield :page_title%></title>
</head>
<body>
  <%=yield :page_content%>
</body>
</html>

More

  1. Run gem server to read plain_site rdoc.
  2. Read the source code.

Sites using PlainSite

http://jex.im