Contenticious - build web sites from markdown files
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.
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.
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 help
contenticious
$ contenticious init
which will generate some files and directories:
Now start the server:
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.
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.
index.md
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.
brainfuck.html
Later you will be informed how to customize the contenticious templates. You can adjust the listing by editing the template list.html.ep.
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.
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.
title
H1
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.
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.
app
cached
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.
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.
chached
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.
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.
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
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.
To install Contenticious, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Contenticious
CPAN shell
perl -MCPAN -e shell install Contenticious
For more information on module installation, please visit the detailed CPAN module installation guide.