From 8a5672fdffd87e586c2f97b5f77b7ca7aa7c53c2 Mon Sep 17 00:00:00 2001 From: Kenton Hansen Date: Mon, 10 Oct 2016 15:55:40 -0500 Subject: [PATCH 1/3] Addition of a sample "typical post" So, I thought this section in the docs would be a good place to put the anatomy of a post .md file. --- site/_docs/posts.md | 255 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 site/_docs/posts.md 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. From b1291605b36d978f0fab9fcc7de48879a67ace86 Mon Sep 17 00:00:00 2001 From: Kenton Hansen Date: Mon, 10 Oct 2016 16:46:42 -0500 Subject: [PATCH 2/3] Changes to 'bundle exec jekyll serve' Updated to be consistent with the rest of documentation. --- site/_docs/posts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/_docs/posts.md b/site/_docs/posts.md index bc8628c9..d4d8f15d 100644 --- a/site/_docs/posts.md +++ b/site/_docs/posts.md @@ -122,7 +122,7 @@ 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. +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 `bundle exec 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. From e60769731afc143ca3e2b7fc082be5ec17e16ad9 Mon Sep 17 00:00:00 2001 From: Frank Taillandier Date: Mon, 9 Jan 2017 15:25:59 +0100 Subject: [PATCH 3/3] Report modifications to docs --- docs/_docs/posts.md | 18 ++++ site/_docs/posts.md | 255 -------------------------------------------- 2 files changed, 18 insertions(+), 255 deletions(-) delete mode 100644 site/_docs/posts.md diff --git a/docs/_docs/posts.md b/docs/_docs/posts.md index 40aa8365..d4d8f15d 100644 --- a/docs/_docs/posts.md +++ b/docs/_docs/posts.md @@ -111,6 +111,24 @@ Linking to a PDF for readers to download:

+## 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 `bundle exec 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 diff --git a/site/_docs/posts.md b/site/_docs/posts.md deleted file mode 100644 index d4d8f15d..00000000 --- a/site/_docs/posts.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -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 `bundle exec 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.