Finish anatomy-of-a-great-rust-blog-post

.ruby-version

@@ -1 +1 @@
-2.4.1
+2.5.1

Gemfile.lock

@@ -93,6 +93,8 @@ GEM
     rb-fsevent (0.10.3)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)
+    rb-kqueue (0.2.5)
+      ffi (>= 0.5.0)
     rdiscount (2.2.0.1)
     ref (2.0.0)
     rouge (3.2.1)
@@ -126,6 +128,7 @@ DEPENDENCIES
   nanoc (~> 4.0)
   nokogiri
   rake
+  rb-kqueue (>= 0.2)
   rdiscount
   rouge
   rubypants
@@ -133,4 +136,4 @@ DEPENDENCIES
   systemu
 
 BUNDLED WITH
-   1.16.0
+   1.16.3

TODO

@@ -1,27 +0,0 @@
-Now
----
-
-* Setup monothumb on server
-  * Exclude photo and photos.xml from deploy:rsync
-
-Deployment
-----------
-
-* Move Wordpress to old. and add robots.txt
-
-Later
------
-
-* Add monothumb to GitHub
-* Revise About page content
-  * Get proper lens specs for About page
-* Fully convert to HTML5
-  * Microdata on About/Contact pages
-* Add favicon
-* Add weights to sitemap
-
-Future
-------
-
-* Make it possible to purchase the HTML
-* Make a Wordpress theme out of the site

content/screen.sass

@@ -435,6 +435,10 @@ table
 .text-right
   text-align: right
 
+.heading-icon
+  height: 20px
+  margin-right: 0.25em
+
 // Weather
 body.weather
 

content/technical/2018/08/anatomy-of-a-great-rust-blog-post.md

@@ -1,81 +1,79 @@
 To date I've posted 718 posts to [Read Rust]. I can't profess to having read
-every single one but I have skimmed them all and have definitely extracted
+every single one completely (although I have read a lot of them) but I have at
-the information required to post them to the site. Some blogs make this
+least skimmed them all and extracted the information required to post them to
-easier than others. In this post I cover some things you can do to make your
+the site. Some blogs make this easier than others. In this post I cover some
-blog and the posts upon it easier for readers and myself alike.
+things you can do to make your blog, and the posts upon it, easier for readers
+and myself alike, to read and share with as many people as possible.
 
 I'll cover four areas:
 
 1. Tell a Story
 1. Sign Your Work
 1. Make It Easy to Read Future Posts
-1. Provide Meta Data
+1. Provide Metadata
 
-## Tell a Story
+<h2><img src="/images/2018/noun_Book_1561008.svg" class="heading-icon" alt ="" /> Tell a Story</h2>
 
-A story has a beginning, middle, and end. Blog posts can benefit from this
+A story has a beginning, middle, and end. Blog posts benefit from this
 structure too. The beginning sets the scene, and provides a shared starting
 point for the main content of your post. When a post just dives straight into
-the details, without context it can be hard to work out what the topic is,
+the details without context it can be hard to follow the topic,
-what background there is, or what the motivations behind the work are.
+the background, and the motivations behind the work.
 
-Once you've set the scene in your introduction you can dive into the
+Once you've set the scene in your introduction, you can dig into the details
-details knowing your readers are on the same page. This is where the
+knowing your readers are on the same page, and more likely to follow along. This
-bulk of your post is written.
+is where the bulk of your post is written.
 
 At the end of your post wrap up with a conclusion. This may include a
 summary, details of future work, or unsolved problems.
 
-## Sign Your Work
+<h2><img src="/images/2018/noun_write_1560855.svg" class="heading-icon" alt ="" /> Sign Your Work</h2>
 
 Writing a post takes time and effort. You can be proud of that and sign your
-work! Be it with your real name, a pseudonym, or handle. When posting to
+work! I'm aware that some people prefer not to use their real names online. A
-ReadRust it's important to me to attribute the article to the original author.
+pseudonym, or handle, work well too. When posting to Read Rust it's important to
-I'm aware that some people prefer not to use their real names online and that's
+me to attribute the article to the original author. When there is no
-totally ok. When there is no name, a pseudonym, or handle on a blog it is hard
+information on a post it's hard to work out how to credit the post.
-to work out how to credit the author.
 
-## Make It Easy to Read Future Posts
+<h2><img src="/images/2018/noun_Transmitter_1560979.svg" class="heading-icon" alt ="" /> Make It Easy to Read Future Posts</h2>
 
-So you've written an interesting post that readers have enjoyed, often
+If you've written an interesting post that readers have enjoyed, often they
-they will be interested in reading future posts that you write. You can
+will want to read future posts that you write. You can make this easy using an
-make this easy.
+RSS feed. Pretty much all blogging software supports RSS. If you aren't already
-
-When
-looking for posts for Read Rust it would be impractical for me to
-manually visit the websites of every interesting blog to see if there
-are new posts. That's where [RSS] comes in. RSS lets my subscribe to
-your blog in my feed reader of choice and then it will check for new
-posts on the sites I follow, allowing me to read them all in one place.
-
-Pretty much all blogging software supports RSS. If you aren't already
 generating a feed I highly recommended adding one.
 
-If you already have an RSS on your blog ensure it's easily discoverable by
+If you already have an RSS feed on your blog ensure it's easily discoverable by
-including a link to it on your blog, perhaps in the header, footer, sidebar, or
+linking it. Perhaps in the header, footer, sidebar, or about page. Additionally
-about page. Additionally include a `<link>` tag on the `<head>` of you HTML to
+include a `<link rel="alternate">` tag in the `<head>` of your HTML to make the
-make the feed automatically discoverable.
+feed automatically discoverable by feed readers. MDN have a great tutorial series
+about RSS covering these details: [Syndicating content with RSS][rss].
 
-## Provide Meta Data
+When looking for posts for Read Rust it would be impractical for me to manually
+visit the websites of every interesting blog to see if there are new posts.
+RSS lets me subscribe to blogs in my feed reader of choice ([Feedbin]),
+allowing me and other readers to discover, and read your new posts all in one
+place.
 
-There are actually two audiences for your content: humans and machines.
+<h2><img src="/images/2018/noun_Tag_1560911.svg" class="heading-icon" alt ="" /> Provide Metadata</h2>
-The humans are the readers, the machines are computers such as search
+
-engine indexers, Web Archives, the Read Rust tools! Ideally your content
+There are actually two audiences for your content: humans and machines.  The
-should be easy for both to read.
+humans are the readers, the machines are computers such as [search engine
+indexers][ddg], [web archivers][archive], and the Read Rust tools! Ideally your
+content should be easy for both to read.
 
 The [add-url tool in the Read Rust codebase][add-url] looks for a number
 of pieces of metadata in order to fill in the details that are included
 in the entry for every post:
 
 * **Title** in a `<title>` tag.
-* **Author Name** in a `<meta name="author"` tag.
+* **Author Name** in a `<meta name="author" …>` tag.
-* **Author URL** in a `<link rel="author"` tag.
+* **Author URL** in a `<link rel="author" …>` tag.
 * **Date Published** in a `<time>` tag, typically nested within an `<article>` tag.
-* **Post Summary** (excerpt) in a `<meta name="description"` tag.
+* **Post Summary** (excerpt) in a `<meta name="description" …>` tag.
 
 The tool looks for these in the post itself, as well as in the RSS
 feed if found. Often it still turns up empty. You can help your
-content be more machine readable by including this meta data in your
+content be more machine readable by including this metadata in your
 HTML. The example below shows all of these properties in use.
 
 ```language-html
@@ -107,6 +105,19 @@ HTML. The example below shows all of these properties in use.
 </html>
 ```
 
+So that's it. Four things you can do to help make your blog more readable,
+attributable, and discoverable. Your readers, human and machine will thank you.
 
+With thanks to Gregor Cresnar from the Noun Project for the icons used in this post:
+
+* [Book](https://thenounproject.com/search/?q=book&collection=46510&i=1561008#)
+* [Tag](https://thenounproject.com/search/?q=tag&collection=46510&i=1560911#)
+* [Transmitter](https://thenounproject.com/search/?q=signal&collection=46510&i=1560979#)
+* [Write](https://thenounproject.com/search/?q=write&collection=46510&i=1560855#)
+
+[Feedbin]: http://feedbin.com/
 [add-url]: https://github.com/wezm/read-rust/blob/d41672caaa269fc7f4584e5db2154bd9b3bd3c92/src/bin/add-url.rs
 [Read Rust]: https://readrust.net/
+[ddg]: https://duckduckgo.com/
+[archive]: https://web.archive.org/
+[rss]: https://developer.mozilla.org/en-US/docs/Web/RSS/Getting_Started

content/technical/2018/08/anatomy-of-a-great-rust-blog-post.yaml

@@ -1,6 +1,6 @@
 ---
-title: Writing a Great Rust Blog Post
+title: Anatomy a Great Rust Blog
-extra: Some tips for writing a blog post that is readable by humans and machines alike.
+extra: I've posted 718 articles to Read Rust. This post shares some insights I've gleaned from them, to make your posts as readable and discoverable as possible.
 kind: article
 section: technical
 created_at: 2018-08-18 16:17:00.000000000 +10:00

layouts/article.html

@@ -13,7 +13,7 @@
       <img src="/images/comment.svg" width="32" height="32" alt="Comment icon" class="comment align-top" />
       Stay in touch!
     </h2>
-    <p>Follow me on <a href="https://twitter.com/wezm">Twitter</a>, or <a href="https://mastodon.social/@wezm">Mastodon</a>, <a href="/feed/">subscribe to the feed</a>, or <a href="mailto:wes@wezm.net">send me an email</a>.
+    <p>Follow me on <a href="https://twitter.com/wezm">Twitter</a> or <a href="https://mastodon.social/@wezm">Mastodon</a>, <a href="/feed/">subscribe to the feed</a>, or <a href="mailto:wes@wezm.net">send me an email</a>.
     </p>
   </div>
 </article>

output/images/2018/noun_Book_1561008.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" data-name="Layer 1" viewBox="0 0 100 100" x="0px" y="0px"><path d="M10,18V82a5,5,0,0,0,.13.67c0,.44-.13.87-.13,1.33A14,14,0,0,0,24,98H86a4,4,0,0,0,4-4V6a4,4,0,0,0-4-4H26A16,16,0,0,0,10,18ZM82,90H24a6,6,0,0,1,0-12H82Zm0-20H24a13.89,13.89,0,0,0-6,1.4V18a8,8,0,0,1,8-8H82Z"/><path d="M34,46H66a4,4,0,0,0,4-4V26a4,4,0,0,0-4-4H34a4,4,0,0,0-4,4V42A4,4,0,0,0,34,46Zm4-16H62v8H38Z"/></svg>

output/images/2018/noun_Tag_1560911.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" x="0px" y="0px" viewBox="0 0 100 100" style="enable-background:new 0 0 100 100;" xml:space="preserve"><path d="M86,2H53.2C50,2,47,3.2,44.8,5.6L6.2,44c-5.4,5.4-5.4,14.4,0,19.8l0,0l29.8,30c5.4,5.4,14.4,5.4,19.8,0l0,0l38.6-38.6  C96.6,53,98,50,98,46.8V14C98,7.4,92.6,2,86,2z M90,46.6c0,1-0.4,2-1.2,2.8L50.2,88.2c-2.4,2.4-6.2,2.4-8.4,0l-30-29.8  c-2.4-2.4-2.4-6.2,0-8.4l38.6-38.6c0.8-0.8,1.8-1.2,2.8-1.2H86c2.2,0,4,1.8,4,4V46.6z"/><path d="M72,22c-3.4,0-6,2.6-6,6s2.6,6,6,6s6-2.6,6-6S75.4,22,72,22z"/></svg>

output/images/2018/noun_Transmitter_1560979.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" data-name="Layer 1" viewBox="0 0 100 100" x="0px" y="0px"><path d="M16.06,16.05C-2.82,34.93-3.23,66.42,15.17,84.82a4,4,0,1,0,5.66-5.66C5.5,63.83,5.9,37.52,21.71,21.7a40.07,40.07,0,0,1,56.58,0c15.81,15.82,16.21,42.13.88,57.46a4,4,0,0,0,5.66,5.66c18.4-18.4,18-49.89-.89-68.77A48,48,0,0,0,16.06,16.05Z"/><path d="M72.83,72.82A31.61,31.61,0,0,0,82.1,50.06a32.21,32.21,0,0,0-9.47-22.7,32,32,0,0,0-45.26,0,32.21,32.21,0,0,0-9.47,22.7,31.61,31.61,0,0,0,9.27,22.76,4,4,0,0,0,5.66-5.66,23.62,23.62,0,0,1-6.93-17A24.24,24.24,0,0,1,33,33,24,24,0,0,1,67,33a24.24,24.24,0,0,1,7.13,17.1,23.62,23.62,0,0,1-6.93,17,4,4,0,0,0,5.66,5.66Z"/><path d="M34,90a4,4,0,0,0,0,8H66a4,4,0,0,0,0-8H54V65.42a15.94,15.94,0,0,0,7.31-26.74,16.36,16.36,0,0,0-22.62,0A15.91,15.91,0,0,0,46,65.42V90Zm8-40a8,8,0,1,1,13.66,5.66,8.2,8.2,0,0,1-11.32,0A8,8,0,0,1,42,50Z"/></svg>

output/images/2018/noun_write_1560855.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" data-name="Layer 1" viewBox="0 0 100 100" x="0px" y="0px"><path d="M14,98H74A12,12,0,0,0,86,86V74a4,4,0,0,0-8,0V86a4,4,0,0,1-4,4H14a4,4,0,0,1-4-4V26a4,4,0,0,1,4-4H26a4,4,0,0,0,0-8H14A12,12,0,0,0,2,26V86A12,12,0,0,0,14,98Z"/><path d="M98,6a4,4,0,0,0-4-4H86A56.06,56.06,0,0,0,30,58v6.34L19.17,75.17a4,4,0,0,0,5.66,5.66L35.66,70H42A56,56,0,0,0,83.85,51.13a4,4,0,0,0,.21-5.06l-5.88-8a.14.14,0,0,1,.15-.09H90a4,4,0,0,0,3.69-2.46A55.63,55.63,0,0,0,98,14Zm-8,8a47.71,47.71,0,0,1-2.74,16H78.33A8.17,8.17,0,0,0,71.8,43.07l3.83,5.1A48,48,0,0,1,42,62H38V58A48.05,48.05,0,0,1,86,10h4Z"/></svg>