handroll/handroll

:bento: A website generator for software artisans

handroll

Website development is a finely crafted art.

You need simple. You know what you're doing. You don't want to waste time.

handroll knows you are the boss. With one command, you gracefully blend your theme and content into one precise result.

$ pip install handroll
...
Successfully installed handroll
$ handroll build site
Complete.

Just the facts

handroll walks your website source (i.e. site as shown above), copying everything that it can find. When it encounters:

1. anything ending in .md, the file will be read, the first line of the file will become the title, and the remainder will be converted from Markdown into HTML to become the content. title and content will be combined with a template to produce the final HTML file.
2. any other "known" extension will be handled by a corresponding composer. handroll works with Markdown, reStructuredText, and Textile out of the box.
3. a template (either template.html or anything in templates), the file will be skipped.

Everything else

Check out the feature list to see if handroll meets your needs. If not, please tell us with a GitHub issue or on the mailing list.

All the other stuff you may be interested in regarding handroll (e.g., writing a plugin for your favorite markup language) is found at Read the Docs.

If you want to share some ideas or find announcements, check out the Google Group.

handroll is BSD licensed and tested on Linux and OS X.

Get Involved

Bring an idea to the table! Implement it in a fork or submit an issue to have some discussion about it.

handroll needs a better identity. If you're a web developer or designer, please consider helping with a logo.

Translators can join the fun by translating at the Transifex project. Additional translation details are in thetranslation documentation.

Want to write some code? Running these commands should set up your environment with all the tools you need to contribute.

$ # Start from the root of a handroll clone.
$ virtualenv venv                            # Create your virtual environment.
$ source venv/bin/activate                   # Activate it.
(venv)$ pip install -r requirements-dev.txt  # Install developer tools.
(venv)$ pip install -e .                     # Install handroll in editable mode.
(venv)$ pytest                              # Run the test suite.

handroll's Issues

Translate into Arabic

i18n all the things.

Create a Sitemap extension

It would be helpful to automatically generate a sitemap.xml for web crawlers to provide additional hinting about a site's content.

Add timing

Someone (namely, me) is going to be interested in how handroll performs as it gets working on larger sites. Add some sort of timing output option to show how long a step took.

Example:
Generating HTML for ./2013/zeromq.html ...
[0.01s]

YAML front matter

Files should support YAML front matter to pass extra data onto templates or do other fun stuff.

Include tools to make new sites

handroll should be able to make a basic site with little input. These will be available with the --scaffold flag.

$ handroll -s default

should produce a site.

blog links and titles do not have smartypants quotes.

The extension should apply smartypants to the feed content.

Relative path must be relative to the source

handroll source/ with a relative path of outdir = .. does not put the output in the current directory. Instead, the output goes in the parent directory (i.e. the grandparent of the source). The relative path needs to be anchored to the source directory.

Override sdist to ensure compiled translations

Create a custom sdist command that will be sure to call compile_catalog first so that the mo files are never stale in the release.

Template changes do not update output in watcher

Any modification to a template will not update output files that are affected by the template. handroll needs a template graph concept so that any changes to the template will update the leaf nodes of tree (i.e. any files that use the template).

Modifying template with `handroll -w` triggers multiple copies

Something is a bit off with the handling of templates with the watcher flag. I modified my base template and it made multiple copies of the templates directory in the output.

AtomComposer for atom feed

Try to integrate werkzeug into handroll to create an AtomComposer. The composer should read some kind of feed manifest to create the appropriate atom feed.

TextileComposer

Give some choice. Support .textile users.

Re-enable coveralls

coveralls was disabled because of a strange bug on their server side that was rejecting the reports. It should re-enabled eventually.

Post composition hooks

After handroll is done generating content at the destination, it would be cool to have a hook to run some post processing work.

For example, a link verifier could build a catalog of every link it finds in HTML and check if that link is possible in the output area. This would catch typos and prevent broken links.

Recognize frontmatter without a YAML directive

The current sniffer for detecting frontmatter is very specific and expects a YAML directive (e.g. %YAML 1.1). In practice, I think most people don't do this and would much prefer to start their YAML doc with ---. Make the sniffer flexible enough to detect either option for finding frontmatter.

Update translations for 2.1 release

Create a logo

handroll could use a logo. Here's what I'm looking for in case anyone is interested:

1. The icon should relate to hand roll sushi. I want to tie it to something physical, but I don't want a cigar theme. If other physical things are commonly associated with handrolling, I'm open to that too.
2. If some branding includes the name of the tool, the brand guideline rule is simple: "handroll" is always lowercase.

Skip .swo file types

Another Vim filetype to skip.

Documentation should be part of the release tarball

Users who are offline should be able to look at the handroll docs too.

Use alternate composers

The only composer is the MarkdownComposer for md files. An ability to load arbitrary composers would be cool. For example, a SassComposer for scss files.

Translate to Japanese

i18n all the things

Translate to Chinese

i18n all the things

Fill in the default scaffold with some sample output.

The default scaffold is currently empty.

Suppress pkg_resources UserWarning

pkg_resources started spitting out a stupid warning that really ruins the user experience of handroll. It forces user to take very technical action to fix and is not worth showing.

Suppress the warning.

i18n

Integrate gettext.

Document scaffolds

Write an open graph extension

An extension that would add the correct open graph metadata tags would be helpful.

Excluding YAML directive causes frontmatter to be content

I was wrong about the regex being good enough. When the YAML directive is excluded, the frontmatter gets dumped into the content section. Not good.

Make a development server option

This is a common pattern:

1. Work on a file and want to see changes.
2. Run handroll.
3. Start python -m SimpleHTTPServer to view changes in a webserver.

handroll could grow a watch option (-w or --watch) using watchdog that will listen for filesystem events, incrementally update, and serve the output directory using SimpleHTTPServer.

Only regenerate HTML when template or source has changed

Currently, the Markdown, reStructuredText, and Textile composers will regenerate the page whenever the tool runs. Ideally, the content should only need to be regenerated if the source or the template is modified later than the modified time of the output file.

This will probably be a worthwhile performance boost and be useful for larger sites.

Jinja templates

template.html is convenient for simple stuff, but it would be nice to allow customization with multiple templates. Jinja templates would be a smart way to go.

ReStructuredTextComposer

Give some choice. Support .rst users.

Skip directories

Certain directories created by composers should be ignored (like .sass-cache for the upcoming `SassComposer).

Use SmartyPants extension

Run the Markdown composer through the smartypants extension to get better quoting.

Live reload

It would be awesome if the watch option had a live reload feature.

Make a blog scaffold

Translate to Russian

i18n all the things

Does not ignore junk files

The copier is pretty greedy. It does not ignore stuff like Vim swp files.

Formalize themes

Themes would be a solid way to engage others who may not be programmers.

Highlight the self-contained nature of a site

A handroll site's source can be self contained within the output because the director is smart enough to ignore the source directory.

Because of this feature, a handroll site can live within the output repo. This is a useful feature for GitHub pages because it means that the source and output can exist and the project.github.io page will just do the right thing.

This fact should be documented because it's pretty cool. Something like "single repository configuration."

Make config data available to context

The context should receive site configuration so templates can check the domain and do other related things.

handroll gh-pages website

handroll should have a website to showcase itself. The website should be made with handroll itself to showcase a sample in case someone wants to view the source on GitHub. To get that to work, I think the structure would be something like:

./site <-- source content in here.
./index.html
./...everything else...

This would run like: handroll ./site .. Note: index.html would also be generated from index.md but I'm trying to show that the output would be at the same level as the root of the site source.

Maybe I'll even purchase a domain in the future for said website ("handroll.it" has a nice ring to it).

Composers need access to configuration

The composers have no access to configuration. This creates an inability to use user specified options (e.g. --force).

Relative path output directories

The outdir already supports the home directory expansion, ~. It should also permit relative directories. The most useful pattern would be outdir = '..' for when the output should go in the parent directory. This easily permits a single repository for a site.

Execute anywhere in project

Like git, it would be nice to run handroll from anywhere and it do the right thing.

Use case: I'm writing a blog post in my 2014 directory. I want to :!handroll to have it find the root of my site, and regenerate content. This is superior to :!handroll .. <outdir>.

Implied in this is that my site has knowledge of an outdir location of my choosing. Perhaps there needs to be a handroll.conf.

Devserver doesn't work is source is in output

The development server listens for changes and does nothing if the change is in the output directory (to prevent infinite loops). The checking breaks when the source is in the output directory (e.g., handroll.github.io).

Allow forced composition

There are interesting circumstances when the handroll environment changes so that composition should be needed. There is no way to tell handroll to update anyway. There should be a -f / --force option.

SASSComposer

Work with SASS for .scss files.

Deployment features

Since not everyone uses GitHub for hosting, it would be nice to have some deployment features.

Integrate with coveralls.io

Now that coverage is great, integrate coveralls.io to show it off.