Posts tagged "blog"urn:www-greghendershott-com:blog2013-03-11T19:37:00ZFrog overviewurn:www-greghendershott-com:-2013-03-frog-overview.html2013-03-11T19:37:00Z2013-03-11T19:37:00ZGreg Hendershott
<div>
<article>
<header>
<h1>Frog overview</h1>
<p class="date-and-tags">
<time datetime="2013-03-11" pubdate="true">2013-03-11</time> :: <span class="tags"><a href="/tags/blog.html">blog</a>, <a href="/tags/Frog.html">Frog</a>, <a href="/tags/Racket.html">Racket</a>, <a href="/tags/software.html">software</a></span></p></header>
<blockquote>
<p>UPDATE: This was an early post. For up-to-date info, see <a href="https://github.com/greghendershott/frog">Frog</a>.</p></blockquote>
<p>When the code settles down a bit I’ll put it in a GitHub repo, and write a full README.md. Meanwhile, here’s an overview.</p><!-- more-->
<h2 id="overview">Overview</h2>
<p>Frog is a static web site generator written in <a href="www.racket-lang.org">Racket</a>. You generate files. To deploy, you push them to a GitHub Pages repo, or copy them to Amazon S3, or whatever.</p>
<p>You write content in Markdown.</p>
<p>Posts get a variety of automatic blog features.</p>
<p>You can also create non-post pages.</p>
<p>Yes, it’s very much like Octopress and countless others. But it doesn’t require any Ruby gemmage. The only non-Racket part is optionally using <a href="http://pygments.org/">Pygments</a> to do syntax highlighting.</p>
<h2 id="layout">Layout</h2>
<p>The layout is basically this:</p>
<pre><code>project/
_src/
footer.md
About.md
...
posts/
2013-03-07-a-blog-post-title.md
2013-03-11-another-blog-post-title.md
...
index.html
About.html
sitemap.txt
tags/
feeds/
css/
js/
...</code></pre>
<h2 id="posts">Posts</h2>
<p>You create new posts in <code>_src/posts</code>. They should be named <code>YYYY-MM-DD-TITLE.md</code>. You can do <code>racket frog.rkt -n "My Title"</code> to create such a file easily. This will also fill in the required meta-data section. The markdown file starts with a code block (indented 4 spaces) that must contain these three lines:</p>
<pre><code> Title: A blog post
Date: 2012-01-01T00:00:00
Tags: foo, bar, tag with spaces, baz
Everything from here to the end is your post's contents.
If you put `<--! more -->` on a line, that is the "above-the-fold"
marker. Contents above the line are the "summary" for index pages and
Atom feeds.
<!-- more -->
Contents below `<!-- more -->` are omitted from index pages and Atom
feeds. A "Continue reading..." link is provided instead.
</code></pre>
<p><code>Title</code> can be anything.</p>
<p><code>Date</code> must be an ISO–8601 datetime string: <code>yyyy-mm-ddThr:mn:sc</code>.</p>
<p><code>Tags</code> may be blank (although you have to include the <code>Tags:</code> part).</p>
<h3 id="automatic-post-features">Automatic post features</h3>
<p>As you can see from this blog post, an “On this page” table-of-contents is automatically generated if there are any section headings in your posts.</p>
<p>Posts are automatically included in index pages and feeds.</p>
<p><code>/index.html</code> is an index for all posts, listed newest first.</p>
<p><code>/feeds/all.xml</code> is an Atom feed for all posts.</p>
<p>For each tag, there is a <code>tags/<tag-name>.html</code> index page (also listed newest first) and a <code>/feeds/<tag-name>.xml</code> Atom feed.</p>
<h3 id="the-draft-tag">The <code>DRAFT</code> tag</h3>
<p>The tag <code>DRAFT</code> (all upppercase) causes the post <em>not</em> to be generated.</p>
<p>This way, you can commit the source <code>.md</code> file to your repo, and push, but there will be no corresponding <code>.html</code> generated and pushed. (The use case here is GitHub pages. If you deploy to something like Amazon S3, the similar point is that no <code>.html</code> file will be generated and deployed to that.) <em>I should rewrite this to be more clear about different usage scenarios</em>.</p>
<h2 id="non-post-pages">Non-post pages</h2>
<p>You can put other <code>.md</code> files in <code>_src</code>, and in any subdirs of it. They will be converted to HTML as non-post pages. For example, <code>_src/About.md</code> will be <code>/About.html</code> in the site.</p>
<p>Non-post pages are <em>not</em> included in any automatically generated index pages or feeds. If you want them to be linked in, you must do so manually.</p>
<blockquote>
<p>Note: The navbar is currently hardcoded to look for <code>/About.html</code>, and that’s it. It’s a to-do item to let you specify more items, perhaps using a <code>_src/navbar.md</code> file.</p></blockquote>
<h2 id="footermd">footer.md</h2>
<p>The special file <code>_src/footer.md</code> is converted to HTML and placed at the foot of all pages (both posts and non-post pages).</p>
<h2 id="sitemaptxt">sitemap.txt</h2>
<p>A <code>/sitemap.txt</code> file (for web crawlers) is automatically generated and includes all post and non-post pages. (It does <em>not</em> include index pages for tags.)</p>
<h2 id="sharing-buttons">Sharing buttons</h2>
<p>Sharing buttons for Twitter and Google+ are automatically put at the bottom of posts and non-post pages.</p>
<h2 id="code-blocks">Code blocks</h2>
<p>Frog optionally uses <a href="http://pygments.org/">Pygments</a> to do syntax highlighting. In your markdown using backtick code blocks you can specify a language:</p>
<pre><code>```language
some lines
of code
```</code></pre>
<p>That <em>language</em> is given to Pygments as the lexer to use.</p>
<p>For example this:</p>
<pre><code>```js
/**
* Some JavaScript
*/
function foo()
{
if (counter <= 10)
return;
// it works!
```</code></pre>
<p>Yields this:</p>
<div class="brush: js">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="cm">/**</span>
<span class="cm"> * Some JavaScript</span>
<span class="cm"> */</span>
<span class="kd">function</span> <span class="nx">foo</span><span class="p">()</span>
<span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">counter</span> <span class="o"><=</span> <span class="mi">10</span><span class="p">)</span>
<span class="k">return</span><span class="p">;</span>
<span class="c1">// it works!</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And this:</p>
<pre><code>```racket
#lang racket
;; Finds Racket sources in all subdirs
(for ([path (in-directory)])
(when (regexp-match? #rx"[.]rkt$" path)
(printf "source file: ~a\n" path)))
```</code></pre>
<p>Yields this:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">racket</span>
<span class="c1">;; Finds Racket sources in all subdirs</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">path</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-directory))" style="color: inherit">in-directory</a></span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/regexp.html#(def._((quote._~23~25kernel)._regexp-match~3f))" style="color: inherit">regexp-match?</a></span> <span class="sr">#rx"[.]rkt$"</span> <span class="n">path</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((quote._~23~25kernel)._printf))" style="color: inherit">printf</a></span> <span class="s2">"source file: <a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))" style="color: inherit">~a</a></span><span class="se">\n</span><span class="s2">"</span> <span class="n">path</span><span class="p">)))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>I have a soft spot for <a href="http://pygments.org/">Pygments</a> because it’s actually the first existing open source project to which I contributed. I added a lexer for the <a href="www.racket-lang.org">Racket</a> language. More importantly it has lexers for tons of languages and is used by things like GitHub, BitBucket, and so on. Plus, it fits the spirit of static web site generation better than JavaScript options like <a href="http://alexgorbatchev.com/SyntaxHighlighter/">SyntaxHighlighter</a>.</p>
<h2 id="to-do">To-Do</h2>
<p>What’s left for a “1.0” (or maybe a “Beta 1”):</p>
<ul>
<li>
<p>Some per-project data (such as the author, title, path to Pygments, etc.) are currently Racket parameters. I need to add code to read those from a configuration file.</p></li>
<li>
<p>I need to document the command-line interface.</p></li>
<li>
<p>The command-line interface has a “preview” flag to start a local web server. I’m using something from another project that’s not baked and ready for release. I need to redo this to use the built-in Racket web server.</p></li></ul>
<p>Some things for “1.1” (or “Beta 2”):</p>
<ul>
<li>
<p>Paginate the index pages (show only N posts at a time, with older/newer links).</p></li>
<li>
<p>Get the Bootstrap responsive mode working. It was working for my previous hand-coded site, but for some reason it’s not working for Frog.</p></li>
<li>
<p>Let the user supply a navbar.md to populate the top nav bar. Probably as a Markdown unordered (bullet) list of links.</p></li></ul>
<footer></footer></article></div>Live with Frogurn:www-greghendershott-com:-2013-03-live-with-frog.html2013-03-10T23:14:44Z2013-03-10T23:14:44ZGreg Hendershott
<div>
<article>
<header>
<h1>Live with Frog</h1>
<p class="date-and-tags">
<time datetime="2013-03-10" pubdate="true">2013-03-10</time> :: <span class="tags"><a href="/tags/blog.html">blog</a>, <a href="/tags/Frog.html">Frog</a>, <a href="/tags/Racket.html">Racket</a>, <a href="/tags/software.html">software</a></span></p></header>
<p>OK, I have my site generated using Frog and pushed it to GitHub Pages for <a href="http://www.greghendershott.com">http://www.greghendershott.com</a>.</p>
<p>I want to tweak the CSS. It’s vanilla Bootstrap. Most importantly, I wish the headings were a few points smaller and the body text a few points bigger.</p>
<p>The other remaining item is to do the 301 redirect from Blogger to here. It turns out that this should be ridiculously easy to do with Amazon S3. You can make <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html">a bucket that does nothing but perform 301 redirects</a>. I’ve created such a bucket already, and the redirects work fine. I simply need to update my DNS, for which I’m using Amazon Route 53.</p>
<footer></footer></article></div>Lull while I prepare to change tiresurn:www-greghendershott-com:-2013-03-lull-while-i-prepare-to-change-tires.html2013-03-08T21:27:00Z2013-03-08T21:27:00ZGreg Hendershott
<div>
<article>
<header>
<h1>Lull while I prepare to change tires</h1>
<p class="date-and-tags">
<time datetime="2013-03-08" pubdate="true">2013-03-08</time> :: <span class="tags"><a href="/tags/software.html">software</a>, <a href="/tags/Racket.html">Racket</a>, <a href="/tags/blog.html">blog</a>, <a href="/tags/Frog.html">Frog</a></span></p></header>
<p>I’d been trying to stick to a roughly Tuesday and Thursday schedule for posting here.</p>
<p>I haven’t this week because I’ve been trying to work up a replacement for using Blogger.</p>
<p>Basically, I want to write posts in simple Markdown, and generate the blog statically. To be hosted on GitHub or S3 or whatever. And I want it to use Bootstrap so I don’t have to reinvent that wheel.</p><!-- more-->
<p>I realize a bunch of tools purport to do this. The ones I’ve looked at so far, such as Octopress, require installing a bunch of Ruby hoo-hah. I’m a a Racket guy. And I recently wrote a Markdown parser in Racket (with something else in mind, not this project).</p>
<p>As a result, I’ve been spending the last couple days working on the static site generator.</p>
<p>My working name for it is Frog. As in
<b>fr</b>ozen bl
<b>og</b>.</p>
<p>The gist of it has some together pretty quickly in Racket, which is a joy to use.</p>
<p>The bulk of the work remaining is:</p>
<ol>
<li>
<p>Migrate old posts over. That should be pretty easy.</p></li>
<li>
<p>Decide how much I care about URI compatibility and SEO “link juice”. Specifically, is it OK if <code>blog.greghendershott.com/2013/03/some-title.html</code> changes to <code>www.greghendershott.com/2013-03-08-some-title.html</code>? Or do I want them exacto same? Obviously the latter will be harder and require something to do 301 redirects due to the subdomain change. Maybe I’ll decide I don’t care enough, given how new this blog is and the “link equity” is probably not so great. We’ll see.</p></li></ol>
<footer></footer></article></div>Google+urn:www-greghendershott-com:-2012-02-google.html2012-02-17T00:42:00Z2012-02-17T00:42:00ZGreg Hendershott
<div>
<article>
<header>
<h1>Google+</h1>
<p class="date-and-tags">
<time datetime="2012-02-16" pubdate="true">2012-02-16</time> :: <span class="tags"><a href="/tags/blog.html">blog</a></span></p></header>
<p>In case you hadn’t noticed, I’m not exactly posting here, much.</p>
<p>This is not a firehose of information.</p>
<p>This is not a bountiful font of wisdom from which you can aspire merely to glean a glimmering glimpse of insight.</p>
<p>This is not a haystack containing needles such as the secrets to wealth, popularity, and whiter teeth.</p>
<p>This blog will not cause Comcast to send you a warning that you are about to exceed your 250 GB of unlimited data.</p>
<p>Why? Simply because (a) I don’t have that much to say, and (b) what I do have to say, I’m saying on Google+. That is my de facto “blog”, for now.</p>
<p>See you <a href="https://plus.google.com/u/0/107023078912536369392/posts">there</a>.</p>
<footer></footer></article></div>