Write some docs

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)
 

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

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)
     }
 

components/front_matter/src/page.rs

@@ -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(),

components/search/src/lib.rs

@@ -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;
         }
 

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(())

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"
 

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).

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

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.

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()));