benw2/wezm.net
1
0
Fork 0
forked from wezm/wezm.net
Code Pull requests Activity

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

Browse source
This commit is contained in:
Wesley Moore 2018-08-19 14:39:28 +10:00
parent 8c2f3e9487
commit 2764237730
No known key found for this signature in database
GPG key ID: BF67766C0BC2D0EE
11 changed files with 71 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.ruby-version
View file

@ -1 +1 @@
2.4.1 2.5.1

5
Gemfile.lock
View file

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

27
TODO
View file

@ -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

4
content/screen.sass
View file

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

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

@ -1,77 +1,75 @@
To date I've posted 718 posts to [Read Rust]. I can't profess to having read 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: I'll cover four areas:
1. Tell a Story 1. Tell a Story
1. Sign Your Work 1. Sign Your Work
1. Make It Easy to Read Future Posts 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 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 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 At the end of your post wrap up with a conclusion. This may include a
summary, details of future work, or unsolved problems. 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 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. 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 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 of pieces of metadata in order to fill in the details that are included
in the entry for every post: in the entry for every post:
* **Title** in a `<title>` tag. * **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. * **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 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 feed if found. Often it still turns up empty. You can help your
@ -107,6 +105,19 @@ HTML. The example below shows all of these properties in use.
</html> </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 [add-url]: https://github.com/wezm/read-rust/blob/d41672caaa269fc7f4584e5db2154bd9b3bd3c92/src/bin/add-url.rs
[Read Rust]: https://readrust.net/ [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

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

@ -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 kind: article
section: technical section: technical
created_at: 2018-08-18 16:17:00.000000000 +10:00 created_at: 2018-08-18 16:17:00.000000000 +10:00

2
layouts/article.html
View file

@ -13,7 +13,7 @@
<img src="/images/comment.svg" width="32" height="32" alt="Comment icon" class="comment align-top" /> <img src="/images/comment.svg" width="32" height="32" alt="Comment icon" class="comment align-top" />
Stay in touch! Stay in touch!
</h2> </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> </p>
</div> </div>
</article> </article>

1
output/images/2018/noun_Book_1561008.svg Normal file
View file

@ -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>
Side by side

After

Width:  |  Height:  |  Size: 422 B

1
output/images/2018/noun_Tag_1560911.svg Normal file
View file

@ -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>
Side by side

After

Width:  |  Height:  |  Size: 601 B

1
output/images/2018/noun_Transmitter_1560979.svg Normal file
View file

@ -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>
Side by side

After

Width:  |  Height:  |  Size: 878 B

1
output/images/2018/noun_write_1560855.svg Normal file
View file

@ -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>
Side by side

After

Width:  |  Height:  |  Size: 622 B