AAWWW yeaaa!!! Time to get drilling down to the Raven blog workflow - from getting familiar with Raven's structure to creating your own theme. If you're familiar with Pelican, you'll feel right at home (p^-^)p
AAWWW yeaaa!!! Time to get drilling down to the Raven blog workflow - from getting familiar with Raven's structure to creating your own theme. If you're familiar with Pelican, you'll feel right at home (p^-^)p
--------------------------------------------------------------------------------
/content/raven-doc.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Raven Documentation
3 | date: 2017-06-29
4 | category: projects
5 | summary: AAWWW yeaaa!!! Time to get drilling down to the Raven blog workflow - from getting familiar with Raven's structure to creating your own theme. If you're familiar with Pelican, you'll feel right at home (p^-^)p
6 | ---
7 |
8 | ### Installing Raven
9 |
10 | Once you're set with [npm](https://nodejs.org/en/), whip out your terminal and enter in the following:
11 |
12 | ```ssh
13 | git clone https://github.com/mimoduo/raven.git
14 | cd raven
15 | sudo npm install gulp-cli -g
16 | npm install
17 | gulp
18 | ```
19 |
20 | > **That's it!** Gulp will begin to process all posts, spin up a live reload server, and begin watching for any post, template, icon, or style changes.
21 |
22 | **Now you're officially ready to start creating your new blog by**:
23 |
24 | * [learning Raven's folder structure](#wheres-your),
25 | * [learning how Raven works](#how-raven-works),
26 | * [configuring your blog's settings](#configuring-raven),
27 | * [structuring your blog](#structuring-your-blog),
28 | * [styling your blog](#styling-your-blog),
29 | * and [creating markdown content](#creating-content)!
30 |
31 | ## Where's Your @&#*
32 |
33 | First, let's start with some of the basics of Raven by detailing where everything is:
34 |
35 | * **content**: markdown files representing your blog posts
36 | * **output**: static files generated based on the theme and content
37 | * **themes**: appearance and markup of your blog
38 |
39 | ## How Raven Works
40 |
41 | Raven grabs all the markdown files you've written in the content folder and processes them as such:
42 |
43 | **markdown >> json >> pug :: index/post-detail/categories pages**
44 |
45 | 1. Retrieves the contents of each markdown file
46 | 2. Processes the file's front matter field
47 | 3. Renders the file's markdown content into viable HTML
48 | 4. Pushes a json object representation of the file to a blog array
49 | 5. Sorts the newly created array by date
50 | 6. Sorts the articles by category
51 | 7. Compiles index pages using the blog array
52 | 8. Compiles post detail pages using the blog array
53 | 8. Compiles category pages using the blog array
54 |
55 | ## Configuring Raven
56 |
57 | Raven pulls in the `"data"` object from the **package.json** file to render your blog. *Feel free to add key: value pairs here to help better represent your blog*:
58 |
59 | ```js
60 | "data": {
61 | "site": {
62 | "name": "raven",
63 | "url": "raven.surge.sh"
64 | },
65 | "fonts": [
66 | {
67 | "family": "Oxygen",
68 | "weights": "300,400,700"
69 | }
70 | ],
71 | "analytics": true,
72 | "disqus": {
73 | "include": true,
74 | "shortname": "raven-blog"
75 | },
76 | "static": "output",
77 | "theme": "themes/feather",
78 | "templates": "themes/feather",
79 | "pager": 8,
80 | "links": {
81 | "social": [
82 | {
83 | "name": "Github",
84 | "url": "https://github.com"
85 | },
86 | {
87 | "name": "Codepen",
88 | "url": "https://codepen.io"
89 | }
90 | ]
91 | }
92 | }
93 | ```
94 |
95 | ### Data Object Reference
96 |
97 | * **fonts**: provides pug the data needed to dynamically pull google fonts
98 | * **static**: determines the output directory of static content
99 | * **theme**: determines which sass theme folder to pull from
100 | * **templates**: determines which pug templates folder to pull from
101 | * **pager**: the amount of posts on each index page
102 |
103 | ### Using Data Within Templates
104 |
105 | Data can be referenced within pug by **evaluating template locals**:
106 |
107 | ```pug
108 | //- Render the site name from data: { site: { name: ""}}
109 | h1= data.site.name
110 | p Thanks to the power of Raven my blog, #{data.site.name}, was possible!
111 |
112 | //- Render each link from data: { links: { social: []}}
113 | each link in data.links.social
114 | a(href=link.url)= link.name
115 |
116 | //- Render arbitrary values from data: { custom: ""}
117 | h2= data.custom
118 | ```
119 |
120 | ## Structuring Your Blog
121 |
122 | The first thing you'll likely want to do is modify the templates a bit, starting from base.pug. If you haven't written in pug before, here's an [awesome pug tutorial](http://mimoduo.surge.sh/learn-pug-js-with-pugs.html) for you!
123 |
124 | > **Remember**, all of the variables used within each template are provided to pug from your *package.json's* `"data"` *object* and *each markdown post's front matter*.
125 |
126 | **base.pug** is the foundational template that provides the structure to all other page templates, namely:
127 |
128 | * **index.pug**: *list view for blog articles*
129 | * **post-detail.pug**: *detail view for a specific blog article*
130 |
131 | All other templates are considered **partials** that are included on the aforementioned templates:
132 |
133 | * **post.pug**: foundational template to represent each post
134 | * **pager.pug**: provides the ability to chunk your blog list
135 | * **analytics.pug**: *conditionally included based on your blog's settings*
136 | * **disqus.pug**: *conditionally included based on your blog's settings*
137 |
138 | ## Styling Your Blog
139 |
140 | All of the classes used within the base templates are available to style within the **feather theme** under `/themes/feather/sass/*`. For those new to Sass, here's a quick [sass cheat sheet](https://codepen.io/mimoduo/post/sass-cheat-sheet) for you!
141 |
142 | There are a few utility files to help you through development:
143 |
144 | * normalize.css: *basic reset for browser consistency*
145 | * functions.scss: *several inline font sizing functions for ems & rems*
146 | * variables.scss: *grid variables & a space for custom variables*
147 |
148 | ### Creating Your Own Theme
149 |
150 | Creating your own theme is a piece of cake. Since Raven treats markup and styles separately, you can continue to use the feather theme templates while developing your own theme outside of feather. *Just reconfigure your blog's settings to point to a different theme folder*:
151 |
152 | ```json
153 | "data": {
154 | "theme": "themes/yourTheme"
155 | }
156 | ```
157 |
158 | Afterwards, make sure that your new theme folder contains the following folder structure for gulp to process Sass correctly:
159 |
160 | `/themes/yourTheme/sass/site.scss`
161 |
162 | ## Creating Content
163 |
164 | Each blog article is written in **Markdown** with the addition of **front matter**. If you're diggin for a markdown tutorial, [daring fireball](https://daringfireball.net/projects/markdown/syntax) has you covered! The following front matter meets the minimum requirements for a blog article:
165 |
166 | ```md
167 | ---
168 | title: Blog Post Title Field
169 | date: 2017-07-24
170 | category: navie
171 | summary: Blog Post Summary Field
172 | ---
173 |
174 | # Your Markdown Content!
175 | ```
176 |
177 | After saving this post, you'll notice a new entry on the index page, a new detail page, and a new category in the main navigation.
178 |
179 | ## Fly With the Wind!
180 |
181 | All the basics of Raven have been covered! There's a bit more to explore and a lot more on the way. I hope you enjoy publishing your blog with Raven! And if you have already published your blog, wouldn't you want some free recognition? Jump over to the [Raven github repo](https://github.com/mimoduo/raven) and add your blog to the [Blogs Running Raven](https://github.com/mimoduo/raven#blogs-running-raven) section.
182 |
--------------------------------------------------------------------------------
/output/markdown-style-guide.html:
--------------------------------------------------------------------------------
1 | Raven | Markdown Style Guide
Renders the file's markdown content into viable HTML
\n
Pushes a json object representation of the file to a blog array
\n
Sorts the newly created array by date
\n
Sorts the articles by category
\n
Compiles index pages using the blog array
\n
Compiles post detail pages using the blog array
\n
Compiles category pages using the blog array
\n\n
Configuring Raven
\n
Raven pulls in the "data" object from the package.json file to render your blog. Feel free to add key: value pairs here to help better represent your blog:
fonts: provides pug the data needed to dynamically pull google fonts
\n
static: determines the output directory of static content
\n
theme: determines which sass theme folder to pull from
\n
templates: determines which pug templates folder to pull from
\n
pager: the amount of posts on each index page
\n
\n
Using Data Within Templates
\n
Data can be referenced within pug by evaluating template locals:
\n
//- Render the site name from data: { site: { name: ""}}\nh1= data.site.name\np Thanks to the power of Raven my blog, #{data.site.name}, was possible!\n\n//- Render each link from data: { links: { social: []}}\neach link in data.links.social\n a(href=link.url)= link.name\n\n//- Render arbitrary values from data: { custom: ""}\nh2= data.custom\n
\n
Structuring Your Blog
\n
The first thing you'll likely want to do is modify the templates a bit, starting from base.pug. If you haven't written in pug before, here's an awesome pug tutorial for you!
\n
\n
Remember, all of the variables used within each template are provided to pug from your package.json's"data"object and each markdown post's front matter.
\n
\n
base.pug is the foundational template that provides the structure to all other page templates, namely:
\n
\n
index.pug: list view for blog articles
\n
post-detail.pug: detail view for a specific blog article
\n
\n
All other templates are considered partials that are included on the aforementioned templates:
\n
\n
post.pug: foundational template to represent each post
\n
pager.pug: provides the ability to chunk your blog list
\n
analytics.pug: conditionally included based on your blog's settings
\n
disqus.pug: conditionally included based on your blog's settings
\n
\n
Styling Your Blog
\n
All of the classes used within the base templates are available to style within the feather theme under /themes/feather/sass/*. For those new to Sass, here's a quick sass cheat sheet for you!
\n
There are a few utility files to help you through development:
\n
\n
normalize.css: basic reset for browser consistency
\n
functions.scss: several inline font sizing functions for ems & rems
\n
variables.scss: grid variables & a space for custom variables
\n
\n
Creating Your Own Theme
\n
Creating your own theme is a piece of cake. Since Raven treats markup and styles separately, you can continue to use the feather theme templates while developing your own theme outside of feather. Just reconfigure your blog's settings to point to a different theme folder:
Afterwards, make sure that your new theme folder contains the following folder structure for gulp to process Sass correctly:
\n
/themes/yourTheme/sass/site.scss
\n
Creating Content
\n
Each blog article is written in Markdown with the addition of front matter. If you're diggin for a markdown tutorial, daring fireball has you covered! The following front matter meets the minimum requirements for a blog article:
\n
---\ntitle: Blog Post Title Field\ndate: 2017-07-24\ncategory: navie\nsummary: Blog Post Summary Field\n---\n\n# Your Markdown Content!\n
\n
After saving this post, you'll notice a new entry on the index page, a new detail page, and a new category in the main navigation.
\n
Fly With the Wind!
\n
All the basics of Raven have been covered! There's a bit more to explore and a lot more on the way. I hope you enjoy publishing your blog with Raven! And if you have already published your blog, wouldn't you want some free recognition? Jump over to the Raven github repo and add your blog to the Blogs Running Raven section.
\n",
40 | "url": "http://raven.surge.sh/raven-doc.html",
41 | "title": "Raven Documentation",
42 | "summary": "AAWWW yeaaa!!! Time to get drilling down to the Raven blog workflow - from getting familiar with Raven's structure to creating your own theme. If you're familiar with Pelican, you'll feel right at home (p^-^)p",
43 | "date_modified": "2017-06-29T00:00:00Z",
44 | "author": {
45 | "name": "Bryan Stoner",
46 | "url": "http://mimoduo.surge.sh/"
47 | }
48 | }
49 | ]
50 | }
--------------------------------------------------------------------------------
/output/feed.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Raven
5 | http://raven.surge.sh/
6 | A refined and flexible static blog generator
7 | Mon, 09 Oct 2017 20:42:56 GMT
8 | http://blogs.law.harvard.edu/tech/rss
9 | Feed for Node.js
10 |
11 | Raven
12 | http://raven.surge.sh/favicon-32x32.png
13 | http://raven.surge.sh/
14 |
15 | All rights reserved 2017, Bryan Stoner
16 |
17 |
18 | <![CDATA[From the Future]]>
19 | http://raven.surge.sh/future-post.html
20 | http://raven.surge.sh/future-post.html
21 | Thu, 29 Jun 2220 00:00:00 GMT
22 |
23 | mimoduo@gmail.com (Bryan Stoner)
24 |
25 |
26 | <![CDATA[Markdown Style Guide]]>
27 | http://raven.surge.sh/markdown-style-guide.html
28 | http://raven.surge.sh/markdown-style-guide.html
29 | Wed, 28 Jun 2017 00:00:00 GMT
30 |
31 | h1
32 |
Heading 1 has 1 pounds sign.
33 |
h2
34 |
Heading 2 has 2 pounds signs.
35 |
h3
36 |
Heading 3 has 3 pounds signs.
37 |
h4
38 |
Heading 4 has 4 pounds signs.
39 |
h5
40 |
Heading 5 has 5 pounds signs.
41 |
h6
42 |
Heading 6 has 6 pounds signs.
43 |
Formatting Text
44 |
A paragraph can be as simple as bolded text or as hard as italicized marks. Yet creating a link can be as easy as pie.
45 |
Blockquotes
46 |
47 |
And there's always the trusty blockquote to emphasize an incredible situation.
Renders the file's markdown content into viable HTML
129 |
Pushes a json object representation of the file to a blog array
130 |
Sorts the newly created array by date
131 |
Sorts the articles by category
132 |
Compiles index pages using the blog array
133 |
Compiles post detail pages using the blog array
134 |
Compiles category pages using the blog array
135 |
136 |
Configuring Raven
137 |
Raven pulls in the "data" object from the package.json file to render your blog. Feel free to add key: value pairs here to help better represent your blog:
fonts: provides pug the data needed to dynamically pull google fonts
175 |
static: determines the output directory of static content
176 |
theme: determines which sass theme folder to pull from
177 |
templates: determines which pug templates folder to pull from
178 |
pager: the amount of posts on each index page
179 |
180 |
Using Data Within Templates
181 |
Data can be referenced within pug by evaluating template locals:
182 |
//- Render the site name from data: { site: { name: ""}}
183 | h1= data.site.name
184 | p Thanks to the power of Raven my blog, #{data.site.name}, was possible!
185 |
186 | //- Render each link from data: { links: { social: []}}
187 | each link in data.links.social
188 | a(href=link.url)= link.name
189 |
190 | //- Render arbitrary values from data: { custom: ""}
191 | h2= data.custom
192 |
193 |
Structuring Your Blog
194 |
The first thing you'll likely want to do is modify the templates a bit, starting from base.pug. If you haven't written in pug before, here's an awesome pug tutorial for you!
195 |
196 |
Remember, all of the variables used within each template are provided to pug from your package.json's"data"object and each markdown post's front matter.
197 |
198 |
base.pug is the foundational template that provides the structure to all other page templates, namely:
199 |
200 |
index.pug: list view for blog articles
201 |
post-detail.pug: detail view for a specific blog article
202 |
203 |
All other templates are considered partials that are included on the aforementioned templates:
204 |
205 |
post.pug: foundational template to represent each post
206 |
pager.pug: provides the ability to chunk your blog list
207 |
analytics.pug: conditionally included based on your blog's settings
208 |
disqus.pug: conditionally included based on your blog's settings
209 |
210 |
Styling Your Blog
211 |
All of the classes used within the base templates are available to style within the feather theme under /themes/feather/sass/*. For those new to Sass, here's a quick sass cheat sheet for you!
212 |
There are a few utility files to help you through development:
213 |
214 |
normalize.css: basic reset for browser consistency
215 |
functions.scss: several inline font sizing functions for ems & rems
216 |
variables.scss: grid variables & a space for custom variables
217 |
218 |
Creating Your Own Theme
219 |
Creating your own theme is a piece of cake. Since Raven treats markup and styles separately, you can continue to use the feather theme templates while developing your own theme outside of feather. Just reconfigure your blog's settings to point to a different theme folder:
Afterwards, make sure that your new theme folder contains the following folder structure for gulp to process Sass correctly:
225 |
/themes/yourTheme/sass/site.scss
226 |
Creating Content
227 |
Each blog article is written in Markdown with the addition of front matter. If you're diggin for a markdown tutorial, daring fireball has you covered! The following front matter meets the minimum requirements for a blog article:
228 |
---
229 | title: Blog Post Title Field
230 | date: 2017-07-24
231 | category: navie
232 | summary: Blog Post Summary Field
233 | ---
234 |
235 | # Your Markdown Content!
236 |
237 |
After saving this post, you'll notice a new entry on the index page, a new detail page, and a new category in the main navigation.
238 |
Fly With the Wind!
239 |
All the basics of Raven have been covered! There's a bit more to explore and a lot more on the way. I hope you enjoy publishing your blog with Raven! And if you have already published your blog, wouldn't you want some free recognition? Jump over to the Raven github repo and add your blog to the Blogs Running Raven section.
Renders the file's markdown content into viable HTML
141 |
Pushes a json object representation of the file to a blog array
142 |
Sorts the newly created array by date
143 |
Sorts the articles by category
144 |
Compiles index pages using the blog array
145 |
Compiles post detail pages using the blog array
146 |
Compiles category pages using the blog array
147 |
148 |
Configuring Raven
149 |
Raven pulls in the "data" object from the package.json file to render your blog. Feel free to add key: value pairs here to help better represent your blog:
fonts: provides pug the data needed to dynamically pull google fonts
187 |
static: determines the output directory of static content
188 |
theme: determines which sass theme folder to pull from
189 |
templates: determines which pug templates folder to pull from
190 |
pager: the amount of posts on each index page
191 |
192 |
Using Data Within Templates
193 |
Data can be referenced within pug by evaluating template locals:
194 |
//- Render the site name from data: { site: { name: ""}}
195 | h1= data.site.name
196 | p Thanks to the power of Raven my blog, #{data.site.name}, was possible!
197 |
198 | //- Render each link from data: { links: { social: []}}
199 | each link in data.links.social
200 | a(href=link.url)= link.name
201 |
202 | //- Render arbitrary values from data: { custom: ""}
203 | h2= data.custom
204 |
205 |
Structuring Your Blog
206 |
The first thing you'll likely want to do is modify the templates a bit, starting from base.pug. If you haven't written in pug before, here's an awesome pug tutorial for you!
207 |
208 |
Remember, all of the variables used within each template are provided to pug from your package.json's"data"object and each markdown post's front matter.
209 |
210 |
base.pug is the foundational template that provides the structure to all other page templates, namely:
211 |
212 |
index.pug: list view for blog articles
213 |
post-detail.pug: detail view for a specific blog article
214 |
215 |
All other templates are considered partials that are included on the aforementioned templates:
216 |
217 |
post.pug: foundational template to represent each post
218 |
pager.pug: provides the ability to chunk your blog list
219 |
analytics.pug: conditionally included based on your blog's settings
220 |
disqus.pug: conditionally included based on your blog's settings
221 |
222 |
Styling Your Blog
223 |
All of the classes used within the base templates are available to style within the feather theme under /themes/feather/sass/*. For those new to Sass, here's a quick sass cheat sheet for you!
224 |
There are a few utility files to help you through development:
225 |
226 |
normalize.css: basic reset for browser consistency
227 |
functions.scss: several inline font sizing functions for ems & rems
228 |
variables.scss: grid variables & a space for custom variables
229 |
230 |
Creating Your Own Theme
231 |
Creating your own theme is a piece of cake. Since Raven treats markup and styles separately, you can continue to use the feather theme templates while developing your own theme outside of feather. Just reconfigure your blog's settings to point to a different theme folder:
Afterwards, make sure that your new theme folder contains the following folder structure for gulp to process Sass correctly:
237 |
/themes/yourTheme/sass/site.scss
238 |
Creating Content
239 |
Each blog article is written in Markdown with the addition of front matter. If you're diggin for a markdown tutorial, daring fireball has you covered! The following front matter meets the minimum requirements for a blog article:
240 |
---
241 | title: Blog Post Title Field
242 | date: 2017-07-24
243 | category: navie
244 | summary: Blog Post Summary Field
245 | ---
246 |
247 | # Your Markdown Content!
248 |
249 |
After saving this post, you'll notice a new entry on the index page, a new detail page, and a new category in the main navigation.
250 |
Fly With the Wind!
251 |
All the basics of Raven have been covered! There's a bit more to explore and a lot more on the way. I hope you enjoy publishing your blog with Raven! And if you have already published your blog, wouldn't you want some free recognition? Jump over to the Raven github repo and add your blog to the Blogs Running Raven section.
AAWWW yeaaa!!! Time to get drilling down to the Raven blog workflow - from getting familiar with Raven's structure to creating your own theme. If you're familiar with Pelican, you'll feel right at home (p^-^)p
Renders the file's markdown content into viable HTML
35 |
Pushes a json object representation of the file to a blog array
36 |
Sorts the newly created array by date
37 |
Sorts the articles by category
38 |
Compiles index pages using the blog array
39 |
Compiles post detail pages using the blog array
40 |
Compiles category pages using the blog array
41 |
42 |
Configuring Raven
43 |
Raven pulls in the "data" object from the package.json file to render your blog. Feel free to add key: value pairs here to help better represent your blog:
fonts: provides pug the data needed to dynamically pull google fonts
81 |
static: determines the output directory of static content
82 |
theme: determines which sass theme folder to pull from
83 |
templates: determines which pug templates folder to pull from
84 |
pager: the amount of posts on each index page
85 |
86 |
Using Data Within Templates
87 |
Data can be referenced within pug by evaluating template locals:
88 |
//- Render the site name from data: { site: { name: ""}}
89 | h1= data.site.name
90 | p Thanks to the power of Raven my blog, #{data.site.name}, was possible!
91 |
92 | //- Render each link from data: { links: { social: []}}
93 | each link in data.links.social
94 | a(href=link.url)= link.name
95 |
96 | //- Render arbitrary values from data: { custom: ""}
97 | h2= data.custom
98 |
99 |
Structuring Your Blog
100 |
The first thing you'll likely want to do is modify the templates a bit, starting from base.pug. If you haven't written in pug before, here's an awesome pug tutorial for you!
101 |
102 |
Remember, all of the variables used within each template are provided to pug from your package.json's"data"object and each markdown post's front matter.
103 |
104 |
base.pug is the foundational template that provides the structure to all other page templates, namely:
105 |
106 |
index.pug: list view for blog articles
107 |
post-detail.pug: detail view for a specific blog article
108 |
109 |
All other templates are considered partials that are included on the aforementioned templates:
110 |
111 |
post.pug: foundational template to represent each post
112 |
pager.pug: provides the ability to chunk your blog list
113 |
analytics.pug: conditionally included based on your blog's settings
114 |
disqus.pug: conditionally included based on your blog's settings
115 |
116 |
Styling Your Blog
117 |
All of the classes used within the base templates are available to style within the feather theme under /themes/feather/sass/*. For those new to Sass, here's a quick sass cheat sheet for you!
118 |
There are a few utility files to help you through development:
119 |
120 |
normalize.css: basic reset for browser consistency
121 |
functions.scss: several inline font sizing functions for ems & rems
122 |
variables.scss: grid variables & a space for custom variables
123 |
124 |
Creating Your Own Theme
125 |
Creating your own theme is a piece of cake. Since Raven treats markup and styles separately, you can continue to use the feather theme templates while developing your own theme outside of feather. Just reconfigure your blog's settings to point to a different theme folder:
Afterwards, make sure that your new theme folder contains the following folder structure for gulp to process Sass correctly:
131 |
/themes/yourTheme/sass/site.scss
132 |
Creating Content
133 |
Each blog article is written in Markdown with the addition of front matter. If you're diggin for a markdown tutorial, daring fireball has you covered! The following front matter meets the minimum requirements for a blog article:
134 |
---
135 | title: Blog Post Title Field
136 | date: 2017-07-24
137 | category: navie
138 | summary: Blog Post Summary Field
139 | ---
140 |
141 | # Your Markdown Content!
142 |
143 |
After saving this post, you'll notice a new entry on the index page, a new detail page, and a new category in the main navigation.
144 |
Fly With the Wind!
145 |
All the basics of Raven have been covered! There's a bit more to explore and a lot more on the way. I hope you enjoy publishing your blog with Raven! And if you have already published your blog, wouldn't you want some free recognition? Jump over to the Raven github repo and add your blog to the Blogs Running Raven section.