- Quick Start
- Details on source tree organisation
- Using a git repository as the source
- What kind of weird name is this for a static site generator?
- Bugs and issues
- One last thing
Quietly::Confident - a static git-aware site generator written in perl.
Usage: qc <command> [<working directory>] Avalable commands are: init - initialize a new site generate - generate static content from repository serve - serve site on *.8080 daemon - detach from terminal and run in background watch - watch for updates, same as daemon but in forreground
Quietly Confident is a static site generator written in perl.
It is git-aware, which means it is able to use a repository as the source of pages to generate. Quietly Confident understands textfiles as sources in the following formats:
(http://daringfireball.net/projects/markdown/). It considers files with the suffix .md or .txt to be markdown files.
POD is a relatively simple format and widely known among perl developers.
You may just put HTML files as source. Quietly Confident will remove anything not needed as: anything between
<body> tags. It will also remove any
<span> tags and any occurence of style or class attributes. This conversion enables you to use the HTML output produced by MS Word. Just in case, not that I encourage you to do so :)
Quietly Confident does not support any meta data in a source file, as can be seen with many other static site generators (in most cases added as YAML on top of the markdown source). The reason: the first adopter of Quietly Confident will be my wife. And for her it must be as simple as ever possible. So, no fiddling with special things and formats.
The tool generates menus and submenus as well.
Download the source:
$ git clone https://github.com/TLINDEN/Quietly-Confident.git $ cd Quietly-Confident
$ wget http://search.cpan.org/CPAN/authors/id/T/TL/TLINDEN/Quietly-Confident-0.10.tar.gz $ tar xfz Quietly-Confident-0.10.tar.gz $ cd Quietly-Confident-0.10
$ perl Makefile.PL $ make $ sudo make install
Please note that Quietly Confident has some dependencies, which can be installed using CPAN:
$ cpan cpan> install Git::Repository cpan> install Text::Markdown cpan> install Moo cpan> install Template cpan> install HTTP::Server::Brick cpan> install Config::General cpan> install IO::All
You're done with install.
To try Quietly Confident for the first time, you can use it to create the required directory structure for you.
First, create a new empty directory somewhere:
$ mkdir mysite
Now let Quietly Confident create the directories and put some files to start with in it:
$ qc init Creating qc.conf Creating directories mkdir source mkdir public_html mkdir templates Creating basic templates Creating static site
This will create the following directories:
qc.conf source/ source/01-Projects/ source/01-Projects/index.md source/01-Projects/Something.md source/index.md source/about.md public_html/ public_html/css public_html/css/local.css public_html/css/bootstrap-responsive.css public_html/css/bootstrap.min.css public_html/js/ public_html/js/bootstrap.js public_html/js/html5.js public_html/js/jquery.js public_html/favicon.ico templates/ templates/page.tpl templates/index.tpl
Well, this doesn't look that simple, does it? But calm down, you don't have to cope with most of the stuff, unless you want to.
The most interesting part for you is the source/ directory. It contains the source files and directories from which the static site will be generated.
The public_html/ directory is where the actual static pages will be written to and from which they have to be served to the internet.
Finally the templates/ directory contains the templates used for the site. In the default site (which we created here), a basic [Boostrap](http://twitter.github.com/bootstrap/)-based design will be used. You can use it as a starting point or throw it away and write your own. Templates are [Template::Toolkit](http://www.template-toolkit.org/index.html) formatted, which is very simple to use AND very flexible. However, for now ignore this.
To see how it looks, you might just fire up the built-in webserver:
$ qc serve [Tue Oct 30 23:32:03 2012]  Mounted wildcard directory at / [Tue Oct 30 23:32:03 2012]  Server started on http://clearair.intern:8080/
Just point your browser to the displayed uri and there you go.
There are a few rules which you may follow to keep your site organized:
generated url's will always end with / and be normalized. Say you've got a file 01-Undone Projects/Mikey Mouse.md. The url generated for this file will be: /undone-projects/mikey-mouse/.
to order menu entries as you wish, prepend your filenames and directories with numbers like 01-Projects, 02-About.md. Those numbers will be removed and only used internaly for ordering.
if you want to put an image into a page, just put the image somewhere inside the source directory. It doesn't matter, where. Refer to the image in your page without any directory. Quietly Confidence will move the image to the public_html/images/ directory and modify the img html tag accordingly.
Earlier I claimed that Quietly Confidence git-aware. Ok let's take a look.
Suppose, you already followed the steps outlined above to create a basic static site directory structure. Now you can just put the source directory to github:
$ cd source $ git init $ git add $ git commit -m 'first commit' $ git remote add origin https://github.com/[Insert your Account]/MySite.git $ git push -u origin master
No more to do. From now on, Quietly Confidence will check the repository state for each file and directory.
You can use this feature in combination with the daemon function of Quietly Confidence. For this you might need an internet-accessible webspace (heroku service will do as well), where you install Quietly Confidence. There you clone your git repository which contains the site sources and attach Quietly Confidence to it:
$ qc daemon
By using this command, Quietly Confidence will detach itself from the terminal and run in the background. It will then watch the git repository regularly for any changes. If something happens, it will re-generate the static site. Just point some webserver, lighty or apache or whatever else you have at hands, to the public_html/ directory and that's it.
The daemon mode maintains a pidfile in the working directory, usually named qc.pid (can be changed in config file). You can also specify the working directory as the second commandline parameter, which maybe required if you want to run it from a system startup script. An example startup script fro FreeBSD is contained in the source directory. If you're using some other non-BSD unix-mimicking OS, you've got to write your own startup script. sorry.
You might also run the the daemon mode in the foreground without detaching for troubleshooting purposes. For this execute:
$ qc watch
In case if you wonder why I named the tool Quietly Confidence: in the first place I had something like 'gitweb' or 'staticgit' and such generica in mind. But none of them really fitted and in addition sounded way too boring.
I'm a huge fan of Ian Banks The Culture series. The stories are especially famous for its spaceship naming scheme. One of those ships is a General Systems Vehicle with the name Sleeper Service which first occurred in [Excession](http://en.wikipedia.org/wiki/Excession). The ships name is not the original one however, it renamed itself sometime. The original name before renaming were - you guess it - Quietly Confidence. In addition the abbreviation qc gives a cool and short command as well.
So. I named my tool like a spaceship in honor to the said ship, which I liked very much, and in honor to Ian Banks who created one of the best scify novels I've ever read.
You might read more about the Quietly Confidence on its wikipedia page: [GSV Sleeper Service](http://en.wikipedia.org/wiki/GSV_Sleeper_Service).
Just file an issue at Github if you find a bug or think it doesn't behave as predicted. Patches are most welcome though.
There are thousands of static site generators out there. Why the ckin hell did you create another one? In fact I tried some of them, something about 20 different tools. None satisfied my needs: maximum simple input format. Some are using ruby, which I don't use by principle. Some are too old and old-fashioned. Some just didn't work.
T. Linden <tom at linden dot at>
Perl Artistic License