Edit this page on Github

Spress is a static site generator, an application that takes your site and transforms it to final HTML ready to deploy on your hosting. Your content is generated at ./build folder. You can create content using HTML or Markdown syntax. Additionally, with converters, you can add new types of content.

Site structure

This is the typical structure of a Spress site:

.
├── build
├── src
│   ├── content
│   │   ├── posts
│   │   │   ├── 2017-01-01-welcome-new-year.md
|   |   ├── assets
|   |   |   ├── mystyles.css
│   │   ├── index.html
│   │   ├── ...
│   ├── includes
│   ├── layouts
│   ├── plugins
|   ├── themes
|   |   ├── theme01
├── composer.json
└── config.yml
  • config.yml: Contains the configuration data. You can change the behaviour of Spress or create custom variables.
  • composer.json: Contains information about plugins and themes required by your site. See add:plugin, remove:plugin, update:plugin commands.
  • ./src/includes: Contains partials that can be used in the layouts, pages and posts.
  • ./src/layouts: Contains layout files used to organize your content. In your post or page, you can choose the layout in the Front matter:
  • ./src/content: The main content of your site are located in this folder.
  • ./src/content/posts: Contains the blog posts files. Files located at this folder
  • ./src/content/assets: Contains the assets of your site: css, js files for instance. are under posts collection and they have a special name format: year-month-day-title.md. The Front matter of each file let you change these properties.
  • ./src/plugins: Extends the functionality of Spress. See developer docs.
  • ./src/themes: Themes of the site. See themes.
  • ./build: This is where the generated site will be placed.

A page example

Below is an example of a simple page written using Markdown:

---
layout: default
name: "John"
---
Welcome {{ page.name }}
-----------------------

This is an example page.

The block delimited by triple-dashed lines is the Front matter and uses YAML syntax. Inside it you can create custom attributes that are available as variables in page content with Twig syntax: {{ page.your-variable-name }}.

Spress uses Twig as default renderizer (template engine). See its documentation to get more powerful templates.

Pretty URLs

Spress has the ability to generate friendly URL’s by converting files like welcome.md to /welcome/index.html. See permalink documentation.

Spress commands

site:build

Build your site in your build folder.

site:build [-s|--source="./"] [--timezone="..."] [--env="dev"] [--server] [--watch] [--drafts] [--safe]
  • --timezone Set the timezone. E.g: "Europe/Madrid". More timezones.
  • --env Set the environment name. More information.
  • --server The built-in server will run by default at http://localhost:4000.
  • --watch Watch for changes and regenerate your site automatically.
  • --drafts Include the draft post in the transformation.
  • --safe Disable all plugins.
# Build site with source path defined:
$ spress site:build -s /your-site-dir

# Build site with default dir:
$ cd /your-site-dir
$ spress site:build

# Build site and run built-in server and watch for file changes
$ cd /your-site-dir
$ spress site:build --server --watch  # Go to http://localhost:4000

# Build site and watch for changes (regenerated automatically into ./build)
$ cd /your-site-dir
$ spress site:build --watch

# Build site using specific timezone:
$ spress site:build -s /your-site-dir --timezone="Europe/Madrid"

# Build site using production environment:
$ spress site:build --env=prod

# Build site with plugins disabled:
$ spress site:build --safe

new:site

Create a new site.

new:site [path[="./"]] [template[="blank"]] [--force] [--all]
  • template Set the template for the site. Spresso is a built-in theme.
  • --force Force to use the path even though it exists and it's not empty.
  • --all In blank template, creates the complete scaffold.

E.g $ spress new:site /your-site-dir spress/spress-theme-spresso

Additionally, a concrete version of the theme can be set:

$ spress new:site /your-site-dir spress/spress-theme-spresso:2.1.0

The prior example creates a new site using Spresso theme.

new:post

The new:post command helps you generates new posts. By default, the command interacts with the developer to tweak the generation. Any passed option will be used as a default value for the interaction.

new:post [--title="..."] [--layout="default"] [--date="..."]
      [--tags="..."] [--categories="..."]`
  • --title: The title of the post.
  • --layout: The layout of the post.
  • --date: The date assigned to the post.
  • --tags: Comma separated list of tags.
  • --categories: Comma separated list of categories.

new:plugin

Crate a new plugin. See the documentation at developers doc.

new:theme

Spress >= 2.2 Create a new theme that could be based on another one preexists.

new:theme [--repository] [--prefer-source] [--dev] [--no-scripts]
    [--prefer-lock] [--force] [--] [<path>] [<package>]
  • --repository: Pick a different repository (as url or json config) to look for the theme package.
  • --prefer-source: Forces installation of the theme from package sources when possible, including VCS information.
  • --dev: Enables installation of dev-require packages of the theme.
  • --no-scripts: Skips the execution of all scripts defined in composer.json file.
  • --prefer-lock: If there is a composer.lock file in the theme, Spress will use the exact version declared in that.
  • --force: Force creation even if path already exists.
  • path: Path of the new theme. Current folder by default.
  • package: The name of the theme package. blank by default.

e.g: creating a theme based on Spresso

$ spress new:theme mysite spress/spress-theme-spresso

e.g: creating a blank theme:

$ spress new:theme mysite

add:plugin

Spress >= 2.2 Adds plugins and themes to the composer.json file of the current directory and installs them.

add:plugin [--prefer-source] [--dry-run] [--dev] [--no-scripts] [--] <packages>
  • --prefer-source: Forces installation of the plugins from package sources when possible, including VCS information.
  • --dry-run: Outputs the operations but will not execute anything.
  • --dev: Enables installation of dev-require packages of the plugin.
  • --no-scripts: Skips the execution of all scripts defined in composer.json file.
  • packages: List of packages that should be added.

e.g:

$ spress add:plugin spress/github-metadata-plugin

remove:plugin

Spress >= 2.2 Removes plugins and themes from the composer.json file of the current directory.

remove:plugin [--dev] [--no-scripts] [--] <packages>
  • --dev: Remove packages from require-dev section.
  • --no-scripts: Skips the execution of all scripts defined in composer.json file.
  • packages: List of packages that should be removed.

e.g:

$ spress remove:plugin spress/github-metadata-plugin

update:plugin

Spress >= 2.2 Update plugins and themes by the latest version.

update:plugin [--prefer-source] [--dry-run] [--dev] [--no-scripts] [--prefer-lock] [--] [<packages>]
  • --prefer-source: Forces installation of the plugins from package sources when possible, including VCS information.
  • --dry-run: Outputs the operations but will not execute anything.
  • --dev: Enables installation of dev-require packages of the plugin.
  • --no-scripts: Skips the execution of all scripts defined in composer.json file.
  • packages: List of packages that should be updated.
$ spress remove:plugin spress/github-metadata-plugin "spress/spress-theme-spresso:>=2.1"

self-update

self-update or selfupdate command replace your spress.phar by the latest version.