Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
This repository contains all the content and styling for the www.leaflabs.com website, including all blog posts but excluding all documentation. A series of python scripts called Pelican are used to compile content source files and a set of templates into static HTML pages, which can then be uploaded to the server. You'll need to install Pelican to test your changes locally; you can get it and find more advanced documentation at: http://pelican.readthedocs.org On debian wheezy this looks like: sudo apt-get install python-jinja2 python-pygments python-docutils python-markdown sudo easy_install -U markdown sudo easy_install pelican ### Commands To (re)build the website from scratch locally (after making any changes) and serve it up on port 8000: make clean html serve For just drafting blog posts, push straight to the live site; for larger changes (eg, to the theme), push to the staging directory (available at staging.leaflabs.com) first. To push to the server's staging directory: make rsync_upload_staging To push to the live website: make rsync_upload_production Run 'make' with no arguments for a full list of commands (not all are configured). ### Editing Most pages and posts are in "Markdown" syntax (.md files), which is sort of like wikitext. reStructuredText (.rst) and AsciiDoc are also allowed. For Markdown in particular, you can pretty much just use HTML tags if you don't want to learn the syntax. These directions will assume you use Markdown; you can find a complete syntax reference at: http://daringfireball.net/projects/markdown/syntax Two "gotchas" with Markdown are that individual HTML tags must not <span multiple=lines> (but close tag can be on a different line than an open tag), and that blank lines insert breaks or paragraphs in the output. To create a new blog post, copy ./template.md to ./posts/<lower-case-title>.md. Edit the meta data; in particular Title, Date, and Slug must be updated. "Slug" should be the same as title but lower-case-with-dashes, and will be used for the permanent blog post URL. Edit your content and run "make clean html serve" from the top level directory to test your changes. Until the "Status: draft" line is removed, blog posts will not show up in the RSS feed, sitemap, or "/blog/" listings, and will instead end up at "/drafts/post-slug-name.html". For just drafting and posting blog posts, push straight to the live site instead of using staging. To add images to your posts, resize the images to the correct size and put them in ./images/. A full-column-width image is 768px wide; 400px or 300px are pretty good also. Use .jpg for all photos or anything with a gradient, and .png for diagrams and logos (and use indexed mode when there are only a couple colors, like gerbers). Then include the images in your post like: <center> <img src="/static/images/your-file.jpg" alt="give an alt"> <br>Optional caption text </center> DO NOT commit full sized images ("as a backup") or files greater than 100KB or so to this repository, they should stored on flickr or static.leaflabs.com. To insert syntax-highlighted code, indent the code at least 4 spaces and put blank lines above and below. Make sure to indent any internal whitespace lines as well, or the code will get split into chunks. Over ride the automatic syntax detection by putting, eg, ":::c++" or ":::python" in the first line of code. Use ":::text" to just have white text on black background, useful for console output. When your draft looks good, commit all the new files to git, push git, and upload to the live server. Once everybody has checked it out and you want it to go live, remove the "Status: draft" line, re-commit, git push, and rsync upload. The "/blog/" page will list the new post, and it will also be included in the RSS feed and sitemaps.xml. ### URLs The front page is './home.html'. It is a jinja template, not a markdown page, but you can just edit it like HTML (sans the header and footer). The URL of a "page" (not a blog post) is based on it's "slug", which is either deduced from the title of the page or from the 'slug' metadata attribute. The URL of a "post" (not a page) is based on both the date (specified in metadata) and the slug (based on the title, or overwritten in metadata). On the live site, the /docs/ tree (and a handful of older redirects) is handled at the http server level (nginx). Look on the server in `/etc/nginx/sites-available/leaflabs.com` for location/alias entries. ### Theme To edit the site-wide template (header and footer), check in `leaflabs_theme/templates/base.html`. ### Troubleshooting If you get a bunch of warnings like: WARNING: Could not process /home/bnewbold/leaf/posts/the-beaglepede-cometh.md 'tuple' object has no attribute 'keys' WARNING: Could not process /home/bnewbold/leaf/pages/thank-you-for-your-purchase.md 'tuple' object has no attribute 'keys' that seems to be due to an old python-markdown error (see https://github.com/waylan/Python-Markdown/issues/76); if you update to a version of markdown post 2.1.1 it goes away: sudo easy_install -U markdown