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.