From 73ddbf7152876862e18f44d06646c3896b8104f6 Mon Sep 17 00:00:00 2001 From: Vincent Prouillet Date: Wed, 21 Mar 2018 16:18:24 +0100 Subject: [PATCH] Write some docs --- CHANGELOG.md | 1 + components/content/src/page.rs | 2 +- components/content/src/sorting.rs | 2 +- components/front_matter/src/page.rs | 8 +++---- components/search/src/lib.rs | 2 +- components/site/src/lib.rs | 16 ++++++-------- docs/content/documentation/content/page.md | 5 +++++ docs/content/documentation/content/search.md | 22 +++++++++++++++++++ docs/content/documentation/content/section.md | 4 ++++ .../getting-started/configuration.md | 4 ++++ src/cmd/init.rs | 1 - 11 files changed, 50 insertions(+), 17 deletions(-) create mode 100644 docs/content/documentation/content/search.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 46dfb3ff..a75c1e0e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) diff --git a/components/content/src/page.rs b/components/content/src/page.rs index c02680d2..26ebbf2b 100644 --- a/components/content/src/page.rs +++ b/components/content/src/page.rs @@ -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 diff --git a/components/content/src/sorting.rs b/components/content/src/sorting.rs index 89ef9c90..b96c6b1d 100644 --- a/components/content/src/sorting.rs +++ b/components/content/src/sorting.rs @@ -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) } diff --git a/components/front_matter/src/page.rs b/components/front_matter/src/page.rs index a30b68e0..86cde2a9 100644 --- a/components/front_matter/src/page.rs +++ b/components/front_matter/src/page.rs @@ -72,7 +72,7 @@ pub struct PageFrontMatter { #[serde(default, deserialize_with = "from_toml_datetime")] pub date: Option, /// Whether this page is a draft and should be ignored for pagination etc - pub draft: Option, + 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, @@ -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>, + pub aliases: Vec, /// Specify a template different from `page.html` to use for that page #[serde(skip_serializing)] pub template: Option, @@ -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(), diff --git a/components/search/src/lib.rs b/components/search/src/lib.rs index 44365035..ea3bcb21 100644 --- a/components/search/src/lib.rs +++ b/components/search/src/lib.rs @@ -68,7 +68,7 @@ fn add_section_to_index(index: &mut Index, section: &Section) { } for page in §ion.pages { - if !page.meta.in_search_index { + if !page.meta.in_search_index || page.meta.draft { continue; } diff --git a/components/site/src/lib.rs b/components/site/src/lib.rs index 3ab661f4..210f8483 100644 --- a/components/site/src/lib.rs +++ b/components/site/src/lib.rs @@ -597,18 +597,16 @@ 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 { - let mut output_path = self.output_path.to_path_buf(); - for component in alias.split('/') { - output_path.push(&component); + 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); - if !output_path.exists() { - create_directory(&output_path)?; - } + if !output_path.exists() { + 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(()) diff --git a/docs/content/documentation/content/page.md b/docs/content/documentation/content/page.md index 14131a66..1a8b7707 100644 --- a/docs/content/documentation/content/page.md +++ b/docs/content/documentation/content/page.md @@ -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" diff --git a/docs/content/documentation/content/search.md b/docs/content/documentation/content/search.md new file mode 100644 index 00000000..c3e79f55 --- /dev/null +++ b/docs/content/documentation/content/search.md @@ -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). diff --git a/docs/content/documentation/content/section.md b/docs/content/documentation/content/section.md index 00739877..bb5cd28c 100644 --- a/docs/content/documentation/content/section.md +++ b/docs/content/documentation/content/section.md @@ -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 diff --git a/docs/content/documentation/getting-started/configuration.md b/docs/content/documentation/getting-started/configuration.md index 11ed9040..58df27ad 100644 --- a/docs/content/documentation/getting-started/configuration.md +++ b/docs/content/documentation/getting-started/configuration.md @@ -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. diff --git a/src/cmd/init.rs b/src/cmd/init.rs index 8aae24a0..d7b57601 100644 --- a/src/cmd/init.rs +++ b/src/cmd/init.rs @@ -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()));