This repository has been archived by the owner on Jan 30, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
documentation.html
237 lines (220 loc) · 11.1 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Documentation</title>
<meta name="description" content="The tiny website generator">
<meta name="author" content="Grégoire Pineau">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="http://carew.github.io/documentation.html"/>
<link rel="alternate" href="http://carew.github.io/feed/atom.xml" type="application/atom+xml" title="Carew"/>
<!-- Latest compiled and minified CSS --><link rel="stylesheet" href="./css/bootstrap.min.css"><link rel="stylesheet" href="./css/bootstrap-theme.min.css"><link rel="stylesheet" href="http://yandex.st/highlightjs/8.0/styles/pojoaque.min.css"> </head>
<body>
<div class="container">
<div class="page-header">
<ul class="list-inline pull-right">
<li>
<a href="cookbook.html">
Cookbooks
</a>
</li>
<li class="active">
<a href="documentation.html">
Documentation
</a>
</li>
<li>
<a href="news.html">
News
</a>
</li>
</ul>
<h1>
<a href=".">
Carew
</a>
</h1>
</div>
<div class="content">
<h1>
Documentation <small>For the end user</small>
</h1>
<div class="pull-right">
<div class="well"><ul class="nav nav-list"><li class="nav-header">Quick access</li><li><a href="#quick-start">Quick start</a><ul class="nav nav-list"><li><a href="#write-a-blog-post">Write a blog post</a></li><li><a href="#write-a-page">Write a page</a></li><li><a href="#front-matter">Front Matter</a></li><li><a href="#directory-structure">Directory structure</a></li></ul></li><li><a href="#title-a-sample-page-navigations-main">title: A sample page
navigations: main</a></li><li><a href="#usage">Usage</a><ul class="nav nav-list"><li><a href="#build-the-site">Build the site</a></li><li><a href="#create-a-new-blog-post">Create a new blog post</a></li></ul></li><li><a href="#what-next">What next?</a></li></ul></div>
</div>
<h2 id="quick-start">Quick start<a href="#quick-start" class="anchor">#</a></h2>
<p>With carew, you can write simple pages and / or blog posts. Create a new file in
<code>pages/</code> folder to create a new page and in <code>posts/</code> to create a new blog post.</p>
<p>Each one must begin with a YAML front matter. See <a href="#front-matter">Front matter chapter</a>
to see all options. Here is a sample page (<code>pages/index.md</code>):</p>
<pre><code>---
title: How to create a new page?
---
So, how to create a new page?
# Step 1
1. step 1.1
1. step 1.2
1. step 1.3</code></pre>
<p>Then run <code>./carew build</code> and look at <code>index.html</code> in the <code>web/</code> directory.</p>
<h3 id="write-a-blog-post">Write a blog post<a href="#write-a-blog-post" class="anchor">#</a></h3>
<p>The file must be located in the <code>posts/</code> directory and must have a name with
the following format: <code>YYYY-mm-dd-slug.md</code> (for e.g.
<code>posts/2012-09-20-like-a-hacker.md</code>). Here is a sample blog post:</p>
<pre><code>---
title: Blogging Like a Hacker
layout: post
---
# Blogging Like a Hacker
* I’m bloggin yo!
* ORLY?
* YARLY!</code></pre>
<p>Then run <code>./carew build</code> and look at <code>2012/09/20/like-a-hacker.html</code> in the
<code>web/</code> dir.</p>
<h3 id="write-a-page">Write a page<a href="#write-a-page" class="anchor">#</a></h3>
<p>The file must be located in the <code>pages/</code> directory (or in one of its
subdirectory).
Here is a sample page (<code>pages/doc/quick-start.md</code>):</p>
<pre><code>---
title: Quick Start
layout: page
---
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Est, debitis quasi
laborum veniam voluptates praesentium corporis! Soluta, facere, voluptatum
veritatis odio pariatur voluptatem consectetur numquam veniam adipisci
placeat blanditiis magnam!</code></pre>
<p>Then run <code>./carew build</code> and look at <code>doc/quick-start.html</code> in the <code>web/</code> dir.</p>
<h3 id="front-matter">Front Matter<a href="#front-matter" class="anchor">#</a></h3>
<p>In order to be converted from markdown to HTML, a file must start with a
"front matter" which describes the document's meta-information.
Files which don't start with a front matter are simply copied to the <code>web/</code>
directory as is.</p>
<p>Here's a sample of front matter:</p>
<pre><code>---
layout: doc
title: React
desciption: how to use react-php
permalink: react.html
tag: [php, react]
navigation: [main]
author: John Do
---</code></pre>
<ul><li>
<p><strong>layout:</strong> the name of the layout (Twig) to use from the <code>layouts/</code> directory in
order to render the page. If not mentionned, defaults to <code>default</code>, which means
<code>layouts/default.html.twig</code>.
<a href="cookbook/themes.html">See theme documentation for more information</a></p>
</li>
<li>
<p><strong>title:</strong> will be used in the index page and by <code><title></title></code> and
<code><h1></h1></code> HTML tags</p>
</li>
<li>
<p><strong>permalink:</strong> forces the target path of the current document</p>
</li>
<li>
<p><strong>tags:</strong> adds the current document to the given tags, to make it easier to
find</p>
<pre><code>---
tags: [nginx, varnish]
# or
tags:
- nginx
- varnish
---</code></pre>
</li>
<li>
<p><strong>navigations:</strong> adds the current document to a menu:</p>
<pre><code>---
navigation: [main]
---</code></pre>
</li>
</ul><p>All others keys (for example <code>description</code>) will be used in a
<code><meta name="" content="" /></code> HTML tag.</p>
<h3 id="directory-structure">Directory structure<a href="#directory-structure" class="anchor">#</a></h3>
<p>Now you can use the following directories:</p>
<ul><li>
<p><strong>assets:</strong> all of these files will be copied to the web directory. You can
add JavaScript, CSS and images in here</p>
</li>
<li>
<p><strong>layouts:</strong> the layouts are used to render the pages. They have a
<code>.html.twig</code> suffix. You can create base templates and have more specific ones
that extend them using the <code>extends</code> tag. The layouts are rendered with
<a href="http://twig.sensiolabs.com">Twig</a>. <a href="cookbook/themes.html">See theme
documentation for more information</a></p>
</li>
<li>
<p><strong>pages:</strong> markdown files representing pages. Each one must begin with a YAML
front matter. Here is a sample page:</p>
<hr><h2 id="title-a-sample-page-navigations-main">title: A sample page
navigations: main<a href="#title-a-sample-page-navigations-main" class="anchor">#</a></h2>
<p>This is a page.</p>
</li>
<li>
<p><strong>posts:</strong> markdown files representing blog posts. Must be named with the
following format: <code>YYYY-mm-dd-slug.md</code> (for e.g. <code>2012-09-20-like-a-hacker.md</code>)</p>
</li>
<li>
<p><strong>api</strong>: HTML or markdown files. Each one will be rendered in
<code>/api/filename.html</code></p>
</li>
<li>
<p><strong>config.yml:</strong> configuration file. The <code>site</code> section defines variables which
will be used in the Twig templates. Here is a sample:</p>
<pre><code>site:
author: Grégoire Pineau
title: Foo
description: Bar</code></pre>
<p>And in the template:</p>
<pre><code><html>
<head>
<title>{{ site.title }}</title></code></pre>
</li>
</ul><p><a href="cookbook/configuration.html">See configuration documention for more
information</a>.</p>
<h2 id="usage">Usage<a href="#usage" class="anchor">#</a></h2>
<h3 id="build-the-site">Build the site<a href="#build-the-site" class="anchor">#</a></h3>
<p>In order to build the site, you can use the <code>build</code> command:</p>
<pre><code>$ bin/carew build</code></pre>
<p>This will populate the <code>web</code> directory with a set of files that can be deployed
onto any static web server.</p>
<p>You can change input / ouput directory. Run for more information:</p>
<pre><code>$ bin/carew help build</code></pre>
<h3 id="create-a-new-blog-post">Create a new blog post<a href="#create-a-new-blog-post" class="anchor">#</a></h3>
<p>Just run:</p>
<pre><code>$ bin/carew carew:generate:post [--date="..."] "title"</code></pre>
<h2 id="what-next">What next?<a href="#what-next" class="anchor">#</a></h2>
<p>Why not read the whole <a href="cookbook.html">Cookbooks</a>?</p>
<p><ul class="unstyled" style="padding-left:30px"><li class=""><h5><a href="cookbook/configuration.html"><i class="icon-book"></i>
How to configure carew?
</a></h5></li><li class=""><h5><a href="cookbook/helper.html"><i class="icon-book"></i>
Usefull twig function
</a></h5></li><li class=""><h5><a href="cookbook/hosting.html"><i class="icon-book"></i>
How to host a website built with carew?
</a></h5></li><li class=""><h5><a href="cookbook/plugins.html"><i class="icon-book"></i>
How to use and create plugins?
</a></h5></li><li class=""><h5><a href="cookbook/preview.html"><i class="icon-book"></i>
How to preview your content?
</a></h5></li><li class=""><h5><a href="cookbook/tags.html"><i class="icon-book"></i>
How do tags work?
</a></h5></li><li class=""><h5><a href="cookbook/themes.html"><i class="icon-book"></i>
How to use and create themes?
</a></h5></li></ul></p> </div>
<footer>
<p class="text-center">
©
<a href="http://gregoirepineau.fr">
Grégoire Pineau
</a>
2015
<small>
with help from <a href="http://carew.github.com/" target="_blank">Carew</a>
</small>
</p>
</footer>
</div>
<script src="./js/jquery-2.1.0.min.js"></script><script src="./js/bootstrap.min.js"></script><script src="http://yandex.st/highlightjs/8.0/highlight.min.js"></script><script>hljs.initHighlightingOnLoad();</script> </body>
</html>