Mercurial > piecrust2
annotate docs/docs/01_tutorial/01_your-first-blog.md @ 1195:ae9387338db1 draft default tip
admin: add option to publish immediately
| author | Ludovic Chabant <ludovic@chabant.com> |
|---|---|
| date | Fri, 30 Dec 2022 16:48:04 -0800 |
| parents | 70f722a1f447 |
| children |
| rev | line source |
|---|---|
| 246 | 1 --- |
| 2 title: "Part 1: Your First Blog" | |
| 3 --- | |
| 4 | |
| 5 This tutorial walks you through the creation of your first PieCrust website: a | |
| 6 simple blog. | |
| 7 | |
| 8 > Whenever you see something like this: | |
| 9 > | |
| 10 > $ chef blah --something | |
| 11 > | |
| 12 > It means you need to run that command (starting with `chef`) in a terminal or | |
| 13 > command prompt. Text that doesn't start with the dollar sign is the expected | |
| 14 > output of the command. | |
| 15 | |
| 16 We'll assume you already have installed PieCrust on your system. If not, the | |
| 17 installation steps are documented in the ["Getting Started"][1] page. | |
| 18 | |
| 19 Let's also verify you have an up-to-date version of PieCrust. | |
| 20 | |
| 21 $ chef --version | |
| 22 {{piecrust.version}} | |
| 23 | |
| 24 If your version is older, you'll want to update PieCrust: | |
| 25 | |
| 26 $ pip install piecrust -U | |
| 27 | |
| 28 If your version is newer, you're probably looking at old docs! You should be | |
| 29 able to find newer docs at the [official PieCrust website][2]. | |
| 30 | |
| 31 | |
| 32 ## Create the website | |
| 33 | |
| 34 Creating the website can be done with a simple command: | |
| 35 | |
| 36 $ chef init myblog | |
| 37 | |
| 38 This will create a directory called `myblog` in the current directory, and | |
| 39 initialize a PieCrust website in it. If you go inside and look at the contents, | |
| 40 however, you'll be surprised to find that there's not much: | |
| 41 | |
| 42 $ cd mblog | |
| 43 $ ls | |
| 44 config.yml | |
| 45 | |
| 46 There's just a `config.yml` file! But that's the file that differentiates a | |
| 47 random directory with a PieCrust website. PieCrust expects a file named like | |
| 48 that at the root of a website. | |
| 49 | |
| 50 > Because PieCrust websites are all files (mostly text), they fit really nicely | |
| 51 > in a source control repository. This makes it so much easier to backup and | |
| 52 > rollback than with a website running on an SQL database, like Wordpress. | |
| 53 > | |
| 54 > It's recommended that you create such a repository right now. If you want to | |
| 55 > use Git, you would type: | |
| 56 > | |
| 57 > $ git init . | |
| 58 > $ git add . | |
| 59 > $ git commit -m "Initial empty blog." | |
| 60 > | |
| 61 > If you want to use Mercurial, you would type the same commands, but replace | |
| 62 > `git` with `hg`. For other source control systems, please check the | |
| 63 > documentation. | |
| 64 > | |
| 65 > And of course don't forget to commit your changes as you go! | |
| 66 | |
| 67 | |
| 68 ## Preview the website | |
| 69 | |
| 70 At this point, you only have an empty website, but we can still preview it in | |
| 71 the browser! Type: | |
| 72 | |
| 73 $ chef serve | |
| 74 * Running on http://localhost:8080/ | |
| 75 | |
| 76 It should tell you it's started a web server at the address | |
| 77 `http://localhost:8080`. If you type that in your browser's address bar, you | |
| 78 should see PieCrust's welcome and boilerplate page. | |
| 79 | |
| 80 You may notice that the `serve` command is still running. That's because the | |
| 81 server is still running, which is what you want. You can stop the server by | |
| 82 hitting `CTRL+C` at any time, but that means the preview won't work anymore. And | |
| 83 because we still have some work to do, obviously, you'll want to open a new | |
| 84 terminal or command prompt in order to type new commands. | |
| 85 | |
| 86 Now let's add some stuff! | |
| 87 | |
| 88 | |
| 89 ## Add some posts | |
| 90 | |
| 91 To add posts, you just have to create a text file in the correct place with the | |
| 92 correct name. By default, PieCrust expects posts in the `posts/` directory, | |
| 93 with a name like so: `YYYY-MM-DD_title-of-the-post.md`. | |
| 94 | |
| 95 If you're like me, you probably don't know what today's date is, however. And | |
| 96 there's also the risk of a typo... so let's instead use the `prepare` command: | |
| 97 | |
| 98 $ chef prepare post my-first-post | |
| 99 Creating page: posts/2015-02-19_my-first-post.md | |
| 100 | |
| 101 There, it tells you the path of the file it created. Open that file now in your | |
| 102 favorite text editor. You should see something like this: | |
| 103 | |
| 104 --- | |
| 105 title: My First Post | |
| 106 time: '08:21:49' | |
| 107 --- | |
| 108 | |
| 109 This is a brand new page. | |
| 110 | |
| 111 Refresh your browser, and you should see that post instead of the welcome page. | |
| 112 Edit the post's text (under the second `---` line), and refresh your browser. | |
| 113 | |
| 114 Now let's add another post. Run the `prepare` command again: | |
| 115 | |
| 116 $ chef prepare post my-second-post | |
| 117 Creating page: posts/2015-02-19_my-second-post.md | |
| 118 | |
| 119 Refresh your browser, and you can see how your blog's homepage is starting to | |
| 120 shape up as expected, with a reverse-chronological list of your posts. That's | |
| 121 because the default *theme* for new PieCrust websites defines a page template | |
| 122 for the home page that does exactly that. This can totally be overriden, of | |
| 123 course, but it works well as an out-of-the-box experience. | |
| 124 | |
| 125 If you want to change the title of a post, you can edit the `title:` part in the | |
| 126 posts' configuration header (which is what we call that part between the 2 `---` | |
| 127 lines). However, the URL of the post will still have `my-first-post` or | |
| 128 `my-second-post` in it. If you want to change that, you'd have to rename the | |
| 129 file itself. | |
| 130 | |
| 131 > The configuration header is written in [YAML][]. It's usually fairly | |
| 132 > straightforward, but the first hurdle you may run into is if you want to set a | |
| 133 > title to something with characters like `'` or `:` in them. In this case, | |
| 134 > you'll have to add double-quotes (`"`) around the whole thing. | |
| 135 > | |
| 136 > If you're using a decent text editor with syntax highlighting, it should know | |
| 137 > about the YAML syntax and tell you that something's wrong. | |
| 138 | |
| 139 Similarly, if you want to change the date of a post, you'd have to rename the | |
| 140 file. The time of the post is in the configuration header, though, so you can | |
| 141 tweak that in the text file. | |
| 142 | |
| 143 To know more about the different settings you can change in a page's | |
| 144 configuration header, check out the [page configuration reference][pageconfref]. | |
| 145 | |
| 146 | |
|
794
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
147 ## Add some pages |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
148 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
149 Just like posts, pages are text files placed in some specific directory -- the |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
150 appropriately named `pages/` directory. If you create a `pages/foo.md` file, |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
151 you'll get a `/foo.html` page in your published website (or just `/foo` if you |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
152 don't want URLs ending with `.html`). |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
153 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
154 Let's create an "_About_" page for our blog. Once again, we could create the |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
155 text file "by hand" but we can also use the `prepare` command: |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
156 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
157 $ chef prepare page about |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
158 Creating page: pages/about.md |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
159 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
160 Edit that file and change it to something more appropriate... make the title |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
161 something like "_About This Site_", and add some text. |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
162 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
163 You should still have the server running, so type |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
164 `http://localhost:8080/about.html` in the address bar. You should see your new |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
165 page show up. |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
166 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
167 Of course, you probably want a link to that page -- it's not very useful if |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
168 visitors have to know the URL in order to reach it. We could go into layout |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
169 and templating considerations so that we can add it in some kind of sidebar |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
170 menu, but we'll keep this tutorial short for now. Instead, let's just add a link |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
171 to it from one of your blog posts. |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
172 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
173 Open your last created post in a text file, and add something like this: |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
174 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
175 {%raw%} |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
176 You can learn more [about this site here]({{pcurl('about')}}) |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
177 {%endraw%} |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
178 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
179 Go back to the home page (`http://localhost:8080`) in your browser and look for |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
180 that new piece of text. It should feature a hyperlink to your new "_About_" |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
181 page. |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
182 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
183 Here's how this worked: |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
184 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
185 * The `[text here](url)` syntax is [Markdown][mdown] for hyperlink. All the |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
186 posts and pages files have a `.md` extension, which means PieCrust will use |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
187 Markdown to format it. This means you can use things like `*asterisks*` and |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
188 `**double asterisks**` to show *italics* and **bold** things. See any |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
189 [Markdown cheat sheet][mdown] to learn about this simple syntax. |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
190 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
191 * As mentioned above, the part in parenthesis is supposed to be the URL of the |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
192 hyperlink, so you might be wondering why we're writing this weird |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
193 {%raw%}`{{pcurl('about')}}`{%endraw%} thing instead of just something like |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
194 `/about.html`. |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
195 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
196 The reason is that a fixed URL is easy to break -- when you change the root |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
197 URL of your site, or when you change between "ugly" URLs (with the `.html` |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
198 extension) and "pretty" URLs (without the extension), along with a few other |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
199 possible changes. |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
200 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
201 The `pcurl` function generates the URL according to the current situation |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
202 and is therefore much more versatile. You can read [more on routing and |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
203 URL functions][routes], or [more on templating in general][tpl]. |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
204 |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
205 |
| 246 | 206 ## Configuring the website |
| 207 | |
| 208 This is all fine and dandy, but the big title at the top of the home page still | |
| 209 says "_My New Website_", and that's not very personal. Let's configure that. | |
| 210 | |
| 211 Open the `config.yml` file. It's also written in [YAML][], like the posts' | |
| 212 configuration headers. You can change the `site/title` setting easily: | |
| 213 | |
| 214 site: | |
| 215 title: "Ludovic's Blog" | |
| 216 | |
| 217 > Note how, for the rest of this tutorial (and the rest of the documentation!) | |
| 218 > we'll refer to nested configuration settings using *slash* separators. So the | |
| 219 > `site/title` setting refers to the `title` setting inside the `site` setting, | |
| 220 > as shown in the snippet above. | |
| 221 | |
| 222 Refresh your browser, and lo and behold, the new title should be there. | |
| 223 | |
| 224 There are plenty of other things you can configure in the `config.yml` file. For | |
| 225 example, say you don't like the default URL format for posts. That can be | |
| 226 adjusted with the `site/post_url` setting. By default, it is: | |
| 227 | |
| 228 site: | |
|
821
70f722a1f447
docs: Add missing quote in example
Raoul Bourquin <raoul@ccczh.ch>
parents:
817
diff
changeset
|
229 post_url: "%year%/%month%/%day%/%slug%" |
| 246 | 230 |
| 231 The post URL format is defined using some keywords surrounded by percent signs, | |
| 232 as you can see above. The `%year%`, `%month%` and `%day%` keywords should be | |
| 233 self-explanatory -- and they map directly to the post's filename, which, if you | |
| 234 remember, contains the post's date. | |
| 235 | |
| 236 The `%slug%` keyword maps to the post's "*slug*", which is the [part of the URL | |
| 237 that has human-readable words][slug]. In PieCrust's case, it comes from the | |
| 238 part of the filename that comes after the date ("*my-first-post* and | |
| 239 *my-second-post* in this tutorial). | |
| 240 | |
| 241 If, say, your blog has a low chance of slug collision, or has a low post | |
| 242 frequency, and you want to have more minimal URLs, you can change it to: | |
| 243 | |
| 244 site: | |
| 245 post_url: "%year%/%slug%" | |
| 246 | |
| 247 Refresh your browser, and you should see that the posts' URLs are now conforming | |
| 248 to the new format. | |
| 249 | |
| 250 > If your browser was currently displaying a post at the old URL, you will | |
| 251 > suddenly get a "_page not found_" error! That's OK, it's because the post is | |
| 252 > now at the new, shorter URL. Just go back to the root URL, `localhost:8080`. | |
| 253 | |
| 254 See the [site configuration reference][siteconfref] for more information about | |
| 255 all the settings you can change. | |
| 256 | |
| 257 | |
| 258 ## Next steps | |
| 259 | |
| 260 At this point you have a moderately function blog, but it's far from looking | |
| 261 good yet. In the [second part of this tutorial][part2] we'll look at customizing | |
| 262 your website's appearance by editing layouts and templates, and writing CSS | |
| 263 stylesheets and using PieCrust's built-in asset pipeline. | |
| 264 | |
| 265 | |
| 266 | |
| 267 [1]: {{pcurl('getting-started')}} | |
| 268 [2]: {{piecrust.url}} | |
| 269 [yaml]: https://en.wikipedia.org/wiki/YAML | |
| 270 [slug]: http://en.wikipedia.org/wiki/Semantic_URL#Slug | |
| 271 [pageconfref]: {{pcurl('docs/reference/page-config')}} | |
|
817
4cbd534f68b0
docs: Repair some broken links
Raoul Bourquin <raoul@ccczh.ch>
parents:
794
diff
changeset
|
272 [siteconfref]: {{pcurl('docs/reference/website-config')}} |
| 246 | 273 [part2]: {{pcurl('docs/tutorial/making-things-pretty')}} |
|
794
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
274 [routes]: {{docurl('content-model/routes')}} |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
275 [tpl]: {{docurl('content/templating')}} |
|
f0fbf218cf44
docs: Tutorial chapter about adding pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
246
diff
changeset
|
276 [mdown]: http://commonmark.org/help/ |
| 246 | 277 |