diff --git a/site/_docs/posts.md b/site/_docs/posts.md new file mode 100644 index 00000000..bc8628c9 --- /dev/null +++ b/site/_docs/posts.md @@ -0,0 +1,255 @@ +--- +layout: docs +title: Writing posts +permalink: /docs/posts/ +--- + +One of Jekyll’s best aspects is that it is “blog aware”. What does this mean, +exactly? Well, simply put, it means that blogging is baked into Jekyll’s +functionality. If you write articles and publish them online, you can publish +and maintain a blog simply by managing a folder of text-files on your computer. +Compared to the hassle of configuring and maintaining databases and web-based +CMS systems, this will be a welcome change! + +## The Posts Folder + +As explained on the [directory structure](../structure/) page, the `_posts` +folder is where your blog posts will live. These files are generally +[Markdown](https://daringfireball.net/projects/markdown/) or HTML, but can +be other formats with the proper converter installed. +All posts must have [YAML Front Matter](../frontmatter/), and they will be +converted from their source format into an HTML page that is part of your +static site. + +### Creating Post Files + +To create a new post, all you need to do is create a file in the `_posts` +directory. How you name files in this folder is important. Jekyll requires blog +post files to be named according to the following format: + +```sh +YEAR-MONTH-DAY-title.MARKUP +``` + +Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit +numbers, and `MARKUP` is the file extension representing the format used in the +file. For example, the following are examples of valid post filenames: + +```sh +2011-12-31-new-years-eve-is-awesome.md +2012-09-12-how-to-write-a-blog.md +``` + +
+
ProTip™: Link to other posts
+

+ Use the post_url + tag to link to other posts without having to worry about the URL's + breaking when the site permalink style changes. +

+
+ +### Content Formats + +All blog post files must begin with [YAML Front Matter](../frontmatter/). After +that, it's simply a matter of deciding which format you prefer. Jekyll supports +[Markdown](https://daringfireball.net/projects/markdown/) out of the box, +and has [myriad extensions for other formats as well](/docs/plugins/#converters-1), +including the popular [Textile](http://redcloth.org/textile) format. These +formats each have their own way of marking up different types of content +within a post, so you should familiarize yourself with these formats and +decide which one best suits your needs. + +
+
Be aware of character sets
+

+ Content processors can modify certain characters to make them look nicer. + For example, the smart extension in Redcarpet converts standard, + ASCII quotation characters to curly, Unicode ones. In order for the browser + to display those characters properly, define the charset meta value by + including <meta charset="utf-8"> in the + <head> of your layout. +

+
+ +## Including images and resources + +Chances are, at some point, you'll want to include images, downloads, or other +digital assets along with your text content. While the syntax for linking to +these resources differs between Markdown and Textile, the problem of working +out where to store these files in your site is something everyone will face. + +Because of Jekyll’s flexibility, there are many solutions to how to do this. +One common solution is to create a folder in the root of the project directory +called something like `assets` or `downloads`, into which any images, downloads +or other resources are placed. Then, from within any post, they can be linked +to using the site’s root as the path for the asset to include. Again, this will +depend on the way your site’s (sub)domain and path are configured, but here are +some examples (in Markdown) of how you could do this using the `site.url` +variable in a post. + +Including an image asset in a post: + +```text +... which is shown in the screenshot below: +![My helpful screenshot]({% raw %}{{ site.url }}{% endraw %}/assets/screenshot.jpg) +``` + +Linking to a PDF for readers to download: + +```text +... you can [get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) directly. +``` + +
+
ProTip™: Link using just the site root URL
+

+ You can skip the {% raw %}{{ site.url }}{% endraw %} variable + if you know your site will only ever be displayed at the + root URL of your domain. In this case you can reference assets directly with + just /path/file.jpg. +

+
+ +## A typical post + +Jekyll can handle many different iterations of the idea you might associate with a "post," however a standard blog style post, including an Title, Layout, Publishing Date, and Categories might look like this: + +``` +--- +layout: post +title: "Welcome to Jekyll!" +date: 2015-11-17 16:16:01 -0600 +categories: jekyll update +--- +You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated. + +To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works. + +``` +Everything in between the first and second `---` are part of the YAML Front Matter, and everything after the second `---` will be rendered with Markdown and show up as "Content." + +## Displaying an index of posts + +It’s all well and good to have posts in a folder, but a blog is no use unless +you have a list of posts somewhere. Creating an index of posts on another page +(or in a [template](../templates/)) is easy, thanks to the [Liquid template +language](https://docs.shopify.com/themes/liquid/basics) and its tags. Here’s a +basic example of how to create a list of links to your blog posts: + +```html + +``` + +Of course, you have full control over how (and where) you display your posts, +and how you structure your site. You should read more about [how templates +work](../templates/) with Jekyll if you want to know more. + +Note that the `post` variable only exists inside the `for` loop above. If +you wish to access the currently-rendering page/posts's variables (the +variables of the post/page that has the `for` loop in it), use the `page` +variable instead. + +## Post excerpts + +Each post automatically takes the first block of text, from the beginning of +the content to the first occurrence of `excerpt_separator`, and sets it as the `post.excerpt`. +Take the above example of an index of posts. Perhaps you want to include +a little hint about the post's content by adding the first paragraph of each of +your posts: + +```html + +``` + +Because Jekyll grabs the first paragraph you will not need to wrap the excerpt +in `p` tags, which is already done for you. These tags can be removed with the +following if you'd prefer: + +```html +{% raw %}{{ post.excerpt | remove: '

' | remove: '

' }}{% endraw %} +``` + +If you don't like the automatically-generated post excerpt, it can be +explicitly overridden by adding an `excerpt` value to your post's YAML +Front Matter. Alternatively, you can choose to define a custom +`excerpt_separator` in the post's YAML front matter: + +```text +--- +excerpt_separator: +--- + +Excerpt + +Out-of-excerpt +``` + +You can also set the `excerpt_separator` globally in your `_config.yml` +configuration file. + +Completely disable excerpts by setting your `excerpt_separator` to `""`. + +Also, as with any output generated by Liquid tags, you can pass the +`| strip_html` filter to remove any html tags in the output. This is +particularly helpful if you wish to output a post excerpt as a +`meta="description"` tag within the post `head`, or anywhere else having +html tags along with the content is not desirable. + +## Highlighting code snippets + +Jekyll also has built-in support for syntax highlighting of code snippets using +either Pygments or Rouge, and including a code snippet in any post is easy. +Just use the dedicated Liquid tag as follows: + +```text +{% raw %}{% highlight ruby %}{% endraw %} +def show + @widget = Widget(params[:id]) + respond_to do |format| + format.html # show.html.erb + format.json { render json: @widget } + end +end +{% raw %}{% endhighlight %}{% endraw %} +``` + +And the output will look like this: + +```ruby +def show + @widget = Widget(params[:id]) + respond_to do |format| + format.html # show.html.erb + format.json { render json: @widget } + end +end +``` + +
+
ProTip™: Show line numbers
+

+ You can make code snippets include line-numbers by adding the word + linenos to the end of the opening highlight tag like this: + {% raw %}{% highlight ruby linenos %}{% endraw %}. +

+
+ +These basics should be enough to get you started writing your first posts. When +you’re ready to dig into what else is possible, you might be interested in +doing things like [customizing post permalinks](../permalinks/) or +using [custom variables](../variables/) in your posts and elsewhere on your +site.