Write some docs

This commit is contained in:
Vincent Prouillet 2018-03-21 16:18:24 +01:00
parent 6100a430c4
commit 73ddbf7152
11 changed files with 50 additions and 17 deletions

View file

@ -8,6 +8,7 @@
to the public directory to the public directory
- Do not require themes to have a static folder - Do not require themes to have a static folder
- Now supports indented Sass syntax - Now supports indented Sass syntax
- Add search index building
## 0.3.2 (2018-03-05) ## 0.3.2 (2018-03-05)

View file

@ -75,7 +75,7 @@ impl Page {
} }
pub fn is_draft(&self) -> bool { pub fn is_draft(&self) -> bool {
self.meta.draft.unwrap_or(false) self.meta.draft
} }
/// Parse a page given the content of the .md file /// Parse a page given the content of the .md file

View file

@ -149,7 +149,7 @@ mod tests {
fn create_draft_page_with_order(order: usize) -> Page { fn create_draft_page_with_order(order: usize) -> Page {
let mut front_matter = PageFrontMatter::default(); let mut front_matter = PageFrontMatter::default();
front_matter.order = Some(order); front_matter.order = Some(order);
front_matter.draft = Some(true); front_matter.draft = true;
Page::new("content/hello.md", front_matter) Page::new("content/hello.md", front_matter)
} }

View file

@ -72,7 +72,7 @@ pub struct PageFrontMatter {
#[serde(default, deserialize_with = "from_toml_datetime")] #[serde(default, deserialize_with = "from_toml_datetime")]
pub date: Option<String>, pub date: Option<String>,
/// Whether this page is a draft and should be ignored for pagination etc /// Whether this page is a draft and should be ignored for pagination etc
pub draft: Option<bool>, pub draft: bool,
/// The page slug. Will be used instead of the filename if present /// The page slug. Will be used instead of the filename if present
/// Can't be an empty string if present /// Can't be an empty string if present
pub slug: Option<String>, pub slug: Option<String>,
@ -91,7 +91,7 @@ pub struct PageFrontMatter {
/// All aliases for that page. Gutenberg will create HTML templates that will /// All aliases for that page. Gutenberg will create HTML templates that will
/// redirect to this /// redirect to this
#[serde(skip_serializing)] #[serde(skip_serializing)]
pub aliases: Option<Vec<String>>, pub aliases: Vec<String>,
/// Specify a template different from `page.html` to use for that page /// Specify a template different from `page.html` to use for that page
#[serde(skip_serializing)] #[serde(skip_serializing)]
pub template: Option<String>, pub template: Option<String>,
@ -170,14 +170,14 @@ impl Default for PageFrontMatter {
title: None, title: None,
description: None, description: None,
date: None, date: None,
draft: None, draft: false,
slug: None, slug: None,
path: None, path: None,
tags: None, tags: None,
category: None, category: None,
order: None, order: None,
weight: None, weight: None,
aliases: None, aliases: Vec::new(),
in_search_index: true, in_search_index: true,
template: None, template: None,
extra: Map::new(), extra: Map::new(),

View file

@ -68,7 +68,7 @@ fn add_section_to_index(index: &mut Index, section: &Section) {
} }
for page in &section.pages { for page in &section.pages {
if !page.meta.in_search_index { if !page.meta.in_search_index || page.meta.draft {
continue; continue;
} }

View file

@ -597,18 +597,16 @@ impl Site {
pub fn render_aliases(&self) -> Result<()> { pub fn render_aliases(&self) -> Result<()> {
for page in self.pages.values() { for page in self.pages.values() {
if let Some(ref aliases) = page.meta.aliases { for alias in &page.meta.aliases {
for alias in aliases { let mut output_path = self.output_path.to_path_buf();
let mut output_path = self.output_path.to_path_buf(); for component in alias.split('/') {
for component in alias.split('/') { output_path.push(&component);
output_path.push(&component);
if !output_path.exists() { if !output_path.exists() {
create_directory(&output_path)?; create_directory(&output_path)?;
}
} }
create_file(&output_path.join("index.html"), &render_redirect_template(&page.permalink, &self.tera)?)?;
} }
create_file(&output_path.join("index.html"), &render_redirect_template(&page.permalink, &self.tera)?)?;
} }
} }
Ok(()) Ok(())

View file

@ -54,6 +54,11 @@ weight = 0
# current one. This takes an array of path, not URLs. # current one. This takes an array of path, not URLs.
aliases = [] aliases = []
# Whether the page should be in the search index. This is only used if
# `build_search_index` is set to true in the config and the parent section
# hasn't set `in_search_index` to false in its front-matter
in_search_index = true
# Template to use to render this page # Template to use to render this page
template = "page.html" template = "page.html"

View file

@ -0,0 +1,22 @@
+++
title = "Search"
weight = 100
+++
Gutenberg can build a search index from the sections and pages content to
be used by a JavaScript library: [elasticlunr](http://elasticlunr.com/).
To enable it, you only need to set `build_search_index = true` in your `config.toml` and Gutenberg will
generate an index for the `default_language` set for all pages not excluded from the search index.
It is very important to set the `default_language` in your `config.toml` if you are writing a site not in
English: the index building pipelines are very different depending on the language.
After `gutenberg build` or `gutenberg serve`, you should see two files in your static directory:
- `search_index.${default_language}.js`: so `search_index.en.js` for a default setup
- `elasticlunr.min.js`
As each site will be different, Gutenberg makes no assumptions about how your search and doesn't provide
the JavaScript/CSS code to do an actual search and display results. You can however look at how this very site
is implementing it to have an idea: [search.js](https://github.com/Keats/gutenberg/tree/master/docs/static/search.js).

View file

@ -52,6 +52,10 @@ paginate_path = "page"
# Options are "left", "right" and "none" # Options are "left", "right" and "none"
insert_anchor_links = "none" insert_anchor_links = "none"
# Whether the section pages should be in the search index. This is only used if
# `build_search_index` is set to true in the config
in_search_index = true
# Whether to render that section homepage or not. # Whether to render that section homepage or not.
# Useful when the section is only there to organize things but is not meant # Useful when the section is only there to organize things but is not meant
# to be used directly # to be used directly

View file

@ -51,6 +51,10 @@ generate_categories_pages = false
# Whether to compile the Sass files found in the `sass` directory # Whether to compile the Sass files found in the `sass` directory
compile_sass = false compile_sass = false
# Whether to build a search index out of the pages and section
# content for the `default_language`
build_search_index = false
# A list of glob patterns specifying asset files to ignore when # A list of glob patterns specifying asset files to ignore when
# processing the content directory. # processing the content directory.
# Defaults to none, which means all asset files are copied over to the public folder. # Defaults to none, which means all asset files are copied over to the public folder.

View file

@ -58,7 +58,6 @@ pub fn create_new_project(name: &str) -> Result<()> {
if compile_sass { if compile_sass {
create_dir(path.join("sass"))?; create_dir(path.join("sass"))?;
} }
// TODO: if search == true, copy a lunr js file embedded in gutenberg
println!(); println!();
console::success(&format!("Done! Your site was created in {:?}", canonicalize(path).unwrap())); console::success(&format!("Done! Your site was created in {:?}", canonicalize(path).unwrap()));