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
- Do not require themes to have a static folder
- Now supports indented Sass syntax
- Add search index building
## 0.3.2 (2018-03-05)

View file

@ -75,7 +75,7 @@ impl Page {
}
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

View file

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

View file

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

View file

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

View file

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

View file

@ -54,6 +54,11 @@ weight = 0
# current one. This takes an array of path, not URLs.
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 = "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"
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.
# Useful when the section is only there to organize things but is not meant
# 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
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
# processing the content directory.
# 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 {
create_dir(path.join("sass"))?;
}
// TODO: if search == true, copy a lunr js file embedded in gutenberg
println!();
console::success(&format!("Done! Your site was created in {:?}", canonicalize(path).unwrap()));