NAME
Contenticious - build web sites from markdown files
SYNOPSIS
Generate config file, directories, example pages and the webapp.pl script:
$ contenticious init
generating contenticious boilerplate...
...
done.
Serve markdown files from pages directory (live updated):
$ ./webapp.pl daemon
...
Server available at http://127.0.0.1:3000.
Generate static files ready for upload (dumped to the dump directory)
$ ./webapp.pl dump
dumping everything to /Users/memowe/code/contenticious/dump ...
...
done!
These examples show basic usage. Contenticious is highly customizable, but you may want to start with this basic commands to see what's happening.
DESCRIPTION
Contenticious is a very simple way to build a nice little website from your content (file-system based).
You just write Markdown files in a directory structure and check the generated HTML live in your browser. The presentation is highly customizable on many levels, but I think the default is readable and rather pretty.
Since Contenticious is a Mojolicious web app, it can "be" a web server for your content, but you can dump everything to static files with a single command and upload it to your favourite web hoster.
It's also possible to mount Contenticious in your Mojolicious web app.
How to start
Change to an empty directory and type contenticious help
in your termina. You'll see a short description of the contenticious
command. Let's start with
$ contenticious init
which will generate some files and directories:
- config - a simple config file with Perl syntax.
- webapp.pl - the web app script which will serve or dump your content
- pages - a directory (structure) in which you'll write Markdown files
- public - a directory with files that will be served directly
Now start the server:
$ ./webapp.pl daemon
...
Server available at http://127.0.0.1:3000.
If you point your web browser to that address, you should see some example pages served directly (and updated live) from the pages directory. Feel free to edit that content and watch what happens in your browser.
On directory and file names
Your directory and file names become url path parts. You may want to add numbers to the directory and file names to get the navigation items in the right order. The numbers will never be seen outside.
To define content for a directory itself you can provide an index.md
file.
file system urls
-------------------------------------------------------
pages
|-- 017_c.md /c.html
|-- 018_perl
| |-- index.md /perl.html
| |-- 01_introduction.md /perl/introduction.html
| '-- 42_the_cpan.md /perl/the_cpan.html
'-- 072_brainfuck /brainfuck.html
|--- 17_turing.md /brainfuck/turing.html
'--- 69_wtf.md /brainfuck/wtf.html
If you don't provide an index.md
file for a directory, contenticious will render a list page for you. See this table for better illustration. In this case, brainfuck.html
will be an auto-generated listing of the two sub pages, turing and wtf.
Later you will be informed how to customize the contenticious templates. You can adjust the listing by editing the template list.html.ep
.
Note: it's impossible to have a directory and a file with the same path name, but I'm pretty sure you don't really need that. Instead use the index.md
mechanism from above.
More about content
Contenticious needs some meta informations about your content files, but it works very hard to guess if you don't provide it. Meta information is provided in the first few lines of your markdown documents and looks like this
title: The Comprehensive Perl Archive Network
navi_name: The CPAN
It's huge, but your mom could eat it
====================================
**CPAN, the Comprehensive Perl Archive Network**,
is an archive of over 100,000 modules of software
written in Perl, as well as documentation for it. ...
The title will show up in the title
HTML element of the pages, which will be rendered in the window title bar in most browsers. If no title line is provided, contenticious will try to extract the first H1
headline of the document's body, which is the mom-line in this case. If there's no H1
headline, contenticious will use the file's path.
The second meta information is navi_name which will be used to generate the site navigation. If no navi_name is provided, contenticious will use the file's path.
Sometimes you'll need static content like images, sound files or PDF documents. No problem, just place them in the public directory and they will be served by contenticious under their own name. After you created the basic pages directory with contenticious
, there's only one static file in public: the default stylesheet.
Customize
To change contenticious' presentation and behaviour, please look at the configuration file config first. It looks like this:
{
pages_dir => app->home->rel_dir('pages'),
dump_dir => app->home->rel_dir('dump'),
name => 'Shagadelic',
copyright => 'Zaphod Beeblebrox',
cached => 0,
}
As you can see, it is a Perl data structure and you can access the app
shortcut for advanced hacking. I think, the most names are rather self-documenting, except cached
. When set to a true value, contenticious will hold the document structure in memory to serve it faster. It's deactivated by default for development. Otherwise you would have to restart the server every time you want to view the latest version.
To change the design of contenticious' pages, edit the styles.css file in the public directory. Since the default HTML is very clean you should be able to change a lot with css changes.
If that's still not enough, use the following command to extract all templates to a newly created templates directory:
$ ./webapp.pl inflate
Then you can change the generated HTML with Mojolicious' flexible ep template syntax.
Deploy
You can find a lot of information about the deployment of Mojolicious apps in its wiki. In most cases you want to set the chached
option to a true value in contenticious' config file to increase performance.
If you plan to deploy your content with Mojolicious' built-in production server Hypnotoad, your contenticious config file is the right place to configure it as well:
{
...
cached => 0,
hypnotoad => {
listen => ['http://*:3000'],
workers => 10,
proxy => 1,
},
}
But if you don't expect your content to be updated very often, just let Contenticious generate static HTML and CSS files for you:
$ ./webapp.pl dump
It will dump everything to the directory dump so you can upload it to your favourite web server without any perl, Mojolicious or contenticious magic.
Mount to an existing web app
With Mojolicious::Plugin::Mount it's possible to mount whole Mojolicious web apps into another. Since Contenticious is a web app (via webapp.pl), you can mount Contenticious too. It works pretty straight-forward. See this distribution's test script t/07_mount.t for an example.
REPOSITORY WITH ISSUE TRACKER
The source code repository of Contenticious is on github: https://github.com/memowe/contenticious
There's also a simple issue tracker. Feel free to use it: https://github.com/memowe/contenticious/issues
AUTHOR AND LICENSE
Copyright (c) Mirko Westermeier, <mail@memowe.de>
Credits:
Maxim Vuets, <maxim.vuets@gmail.com>
Stephan Jauernick, <stephan@stejau.de>
Thank you for your contributions!
Published under the MIT license.