Mercurial > piecrust2

comparison docs/pages/getting-started.md @ 243:26e59f837558

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: Add embryo of a documentation website.
author Ludovic Chabant <ludovic@chabant.com>
date Thu, 19 Feb 2015 08:09:17 -0800
parents
children 1970e7e3a18e
comparison
equal deleted inserted replaced
242:f130365568ff 243:26e59f837558
1 ---
2 title: Getting Started
3 header_class: tutorial
4 ---
5
6 This quick tutorial will show you how to create a simple blog with PieCrust.
7
8 > If you're already an experienced cook, here's the rundown:
9 >
10 > virtualenv pcenv
11 > <activate pcenv>
12 > pip install piecrust
13 > chef init mywebsite
14 > cd mywebsite
15 > chef prepare post my-first-post
16 > chef serve
17 > chef bake
18
19
20 ## Installation
21
22 The first step is obviously to get PieCrust installed on your machine.
23
24 You'll need Python 3.4 at least for this. Note that it can live side by side
25 with Python 2.x. On Windows or MacOSX, you can use the [official Python
26 installer][1]. On main Linux distros, you can use your system's package manager
27 to install it. If you're on a more obscure system, or if you want to use
28 alternative means like Homebrew or something, you probably don't need help for
29 this!
30
31 Now we can start running in a command line. On MacOSX, that's the Terminal app,
32 and on Windows that's the Command Prompt.
33
34
35 ### Global installation
36
37 Python 3 comes with a [package manager][2] called `pip`, with which you can install,
38 update, and uninstall Python programs like PieCrust. Just run:
39
40 pip install piecrust
41
42 This will install PieCrust globally on your system. You may want to install it
43 using a *virtual environment* instead, though. See the next section for that.
44
45 > #### Permission Errors
46 >
47 > If you get some permission errors, you may have to run that command as an
48 > administrator. That would be `sudo pip install piecrust` on MacOSX and Linux, or
49 > running the Command Prompt as an Administrator on Windows.
50
51 You should now have PieCrust installed! You can check that it works by typing:
52
53 chef --version
54
55 If everything's fine it should print `{{piecrust.version}}` (the latest
56 version as of this writing).
57
58
59 ### Using virtual environements
60
61 Although very straightforward, the previous section installs PieCrust globally
62 on your system. This may be OK, but could also cause problems if you have other
63 Python software that share dependencies with PieCrust, but with different
64 versions. And then there's the issue of installing PieCrust in environments in
65 which you don't have administrator access.
66
67 Thankfully, `pip` supports a whole variety of scenarios, and [another
68 utility][3], called `virtualenv` enables even more of them.
69
70 * If you don't have it yet, install `virtualenv` with `pip install
71 virtualenv`, or check with your administrators to have it. Most web hosts
72 provide it.
73 * Run `virtualenv pcenv`. This will create a directory called `pcenv` that
74 contains a whole new Python environment, separate from your system's Python
75 environment.
76 * Activate that environment with `sh pcenv/bin/activate.sh` (on Linux or
77 MacOSX) or `pcenv\Scripts\activate` (on Windows). The new environment will
78 now be active for as long as your current command prompt is active.
79 * Now install PieCrust with `pip install piecrust`. This will install it in
80 that environment, leaving your system's Python clean of any of PieCrust's
81 dependencies.
82
83
84 ## Create an empty website
85
86 The `chef` command is the main PieCrust utility. You can read about it on the
87 [command-line overview][cmdline] page. The first thing to do is to ask it to
88 create a basic website structure:
89
90 chef init mywebsite
91
92 This should create a directory called `mywebsite`. There should be a
93 `config.yml` file in there. Get into that directory:
94
95 cd mywebsite
96
97 Once you're inside a website's root directory, the `chef` command will be able
98 to do a lot of different things.
99
100
101 ## Create new content
102
103 Let's start by creating a new page:
104
105 chef prepare page about-me
106
107 It will tell you that it just created a file named `pages/about-me.md`. Go ahead
108 and edit that in your favorite text editor, and write some text, or change the
109 title that was defined for you in the header part. For more information on
110 writing content, see the documentation about [creating pages][cnt].
111
112 Now let's write a blog post:
113
114 chef prepare post my-new-blog
115
116 It will again tell you about the file it just created. This time it's in the
117 `posts` folder, and has a name that follows some date/title kind of naming
118 convention. You don't have to use `chef prepare` to create content for your
119 website, but for things like blog posts it's a lot easier to let it insert
120 today's date in the filename.
121
122
123 ## Preview content
124
125 Time to preview what we just did! Simply type:
126
127 chef serve
128
129 Open your favorite web browser and navigate to the URL that `chef` is listening
130 on, which by default is `localhost:8080`. You should see some placeholder text
131 along with today's blog post that you just created, with a simple barebones theme.
132
133 > #### Alternate port
134 >
135 > If you already have some other things running on port 8080, you can tell
136 > PieCrust to use a different one with the `-p` option.
137
138 The `about-me` page isn't shown because you're looking at the index page, but
139 you would see it if you navigated to `localhost:8080/about-me`.
140
141
142 ## Bake and publish
143
144 Now it's time to bake this new site and publish it somewhere. There are many
145 ways to do that, as shown in the documentation about [baking][bake], but here's
146 a quick way. Run:
147
148 chef bake
149
150 This will bake the website into static files, stored under the `_counter`
151 directory. At this point, you can upload all the contents of that directory to
152 your web server. When that's done, you should be able to see the exact same
153 website being served from there.
154
155
156 That's it! This is an extremely quick tour of PieCrust. Read the
157 [documentation][doc] to learn more.
158
159
160 [1]: https://www.python.org/downloads/
161 [2]: https://pip.pypa.io/en/latest/
162 [3]: https://virtualenv.pypa.io/en/latest/
163 [doc]: {{pcurl('docs')}}
164 [cmdline]: {{pcurl('docs/general/command-line-overview')}}
165 [cnt]: {{pcurl('docs/content/creating-pages')}}
166 [bake]: {{pcurl('docs/publish')}}
167