Getting Started
This guide should let you start with Phrozn in no time.
Installation
Before you will be able to proceed, you need to install Phrozn. Please, make sure that you meet system requirements outlined on Installation page.
Your first Phrozn project
Let's create our first Phrozn project:
$ mkdir public_html $ cd public_html $ phr init
Here we create public_html folder and within it initialize our new Phrozn project. The output will look
something like this:
Initializing new project Project path: ./public_html/.phrozn/ [ADDED] config.yml [ADDED] entries/index.twig [ADDED] scripts/default.js [ADDED] media/README [ADDED] media/img/README [ADDED] styles/default.less [ADDED] plugins/README [ADDED] archive/README [ADDED] layouts/default.twig
All those files/directories are created in public_html/.phrozn folder.
| Folder | Description |
|---|---|
config.yml |
Site wide configuration file. For details see Site Configuration page. |
layouts |
Folder containing site's layouts. |
entries |
Folder containing posts/entries of your site. You can create entries in one of the supported input formats. Alternatively, you can define your own. |
scripts |
Folder containing client-side scripts (JavaScript). |
styles |
Folder containing stylesheets (CSS, LESS). |
media |
Any media in binary format: flash, images, video files. You can create folder hierarchies which will be
transfered to compiled site's media folder as is. |
plugins |
Folder containing plugins. |
Create some content
You can skip this step and jump to Site
Compilation immediately. Then once you have static site compiled and
want to tweak it more - get back and read this section.
For those of you who want to see the output immediately, sample site has been created: sample.phrozn.info.
First of all, let's start with creating our main layout file, .phrozn/layouts/main.twig
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head>
<title>My Webpage</title>
<link href="/styles/default.css"
rel="stylesheet" media="screen, projection" type="text/css" />
</head>
<body>
<h1>My Webpage</h1>
{{content}}
</body>
</html>
The only special thing here is {{content}} place-holder, which defines the place
where entry's content is to be injected into layout.
Phrozn comes with default layout, called (surprize!!) default.twig, and it is probably more common to
edit it than to create new layout, but for purposes of demonstration, let's proceed with newly created layout
main.twig.
In order to have client-side scripts or styles parsed and compiled into scripts and styles
folders respectively all you need to do is to add them into .phrozn/scripts and
.phrozn/styles. Right now, all JavaScript code is passed without modification, minifying
processors already planned. When it comes to styles you can add them in CSS or LESS format (use "css" and "less" extensions
to distinguish between two).
Now, it is time to create our first entry. All entries go to folder .phrozn/entries and you can have multi-level
directory hierarchies which (depending on your settings) can be preserved in your static site. Source of
.phrozn/entries/test.twig:
layout: main.twig --- <p>My first entry</p>
Entry above is in Twig format (see "twig" extension") but can be in Markdown or Textile. Just change the extension of entry file (twig, textile, markdown etc), and Phrozn will apply respective processor. As mentioned before, you can have your own formats as well - see documentation on creation of custom text processors.
Now let's review front matter.
layout setting is completely optional, it defaults to default.twig, which means
.phrozn/layouts/default.twig is to be used as layout file. Since we created our custom layout file, we set
this option to main.twig.
Compile your project
Now, time to have phrozn version of our project!
$ cd public_html $ phr up
You should get output similar to following:
Starting static site compilation. [OK] Source directory located: /tmp/public_html/.phrozn/ [OK] Destination directory located: /tmp/public_html/ [OK] ./.phrozn/entries/test.twig parsed [OK] ./test.html written [OK] ./.phrozn/styles/default.less parsed [OK] ./styles/default.css written [OK] ./.phrozn/scripts/default.js parsed [OK] ./scripts/default.js written [OK] ./media/README copied [OK] ./media/img/README copied
If public_html is exposed as some web address, say as http://www.domain.com/ then our newly
created page test.html is available at http://www.domain.com/test.html.
If you want to have more readable URLs, just update .phrozn/entries/test.twig, to include permalink
setting:
layout: main.twig title: My readable page title permalink: /sub/folder/:title/ --- <p>My first entry</p>
When you re-run phr up the entry will be written into
public_html/sub/folder/my-readable-page-title/index.html
file, and is available as
http://www.domain.com/sub/folder/my-readable-page-title/.
As you see, other front matter variables are
available in default permalink strategy (see Permalink Strategies).
In this case :title variable was used as a part of final string (additional filtering applied to make it valid URL).
There are number of other options available in entry's front matter.
Keep your project up to date
In order to update your project, all you need to do is call phr up
command. By default, all output files are written into directory containing .phrozn folder, in our case to
public_html:
$ cd public_html # update or add some content $ phr up # by default all ouput will be written to current folder
Purge project
Not the most common thing to do, but should you need to purge the project files you can always do so with clobber command:
$ cd public_html $ phr clobber Purging project data.. Located project folder: /tmp/public_html/.phrozn/ Project folder is to be removed. This operation CAN NOT be undone. Type 'yes' to continue:
Make sure you double check the folder to be purged before typing yes!
Only project folder .phrozn will be removed, your generated content will stay intact.
Summary
Let's summarize what you have learned so far.
You create project using phr init, add some entries/styles/scripts, and compile everything with
phr up. Once you update some source file, you need to update static version of your site, again with
phr up.
Should you create project by mistake, it's always simple to purge it with phr clobber, and start over with
phr init.
Need some samples? Check out git repository of Phrozn's own site.
