update and add more docs to illustrate DemoCards (#69)

Except for some documentation updates, this PR also introduces several new things:

* a DemoCards workflow image
* tricks that I used a lot when writing
* new section: folder manipulation

Author: johnnychen94

README.md

@@ -11,30 +11,44 @@ _Let's focus on writing demos_
 ## Overview
 
 * a plugin package to `Documenter.jl` to manage all your demos.
+* folder structure is the demo structure.
 * minimal configuration.
-* all demos can be tested by CI.
+* CI friendly
 * support demos in markdown and julia format.
 
-The philosophy of DemoCards is "folder structure is structure of demos"; organizing folders and files in
-the following way, then `DemoCards.jl` will help manage the layouts of the index page.
+![democards workflow](docs/quickstart/assets/democards_workflow.png)
+
+The philosophy of DemoCards is "folder structure is the structure of demos"; organizing folders and files in
+the a structural way, then `DemoCards.jl` will help manage how you navigate through the pages.
+
+```text
+examples
+├── part1
+│   ├── assets
+│   ├── demo_1.md
+│   ├── demo_2.md
+│   └── demo_3.md
+└── part2
+    ├── demo_4.jl
+    └── demo_5.jl
+```
+
+DemoCards would understand it in the following way:
 
 ```text
-docs/demos/simplest_demopage
-└── examples
-    ├── part1
-    │   ├── assets
-    │   ├── demo_1.md
-    │   ├── demo_2.md
-    │   └── demo_3.md
-    └── part2
-        ├── assets
-        ├── demo_4.jl
-        └── demo_5.jl
+# Examples
+  ## Part1
+    demo_1.md
+    demo_2.md
+    demo_3.md
+  ## Part2
+    demo_4.jl
+    demo_5.jl
 ```
 
 Read the [Quick Start](https://johnnychen94.github.io/DemoCards.jl/stable/democards/quickstart/index.html) for more instructions.
 
-# Caveat Emptor
+## Caveat Emptor
 
 The use of this package heavily relies on [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl),
 [Literate.jl](https://github.com/fredrikekre/Literate.jl), [Mustache.jl](https://github.com/jverzani/Mustache.jl)

docs/make.jl

@@ -19,9 +19,8 @@ makedocs(format = format,
             "Home" => "index.md",
             quickstart,
             "Concepts" => "concepts.md",
-            "Advanced Usages" => [
-               "Preview only one demo" => "preview.md",
-            ],
+            "Partial build" => "preview.md",
+            "Structure manipulation" => "structure.md",
             "Theme Gallery" => [
                themeless_demopage,
                grid_demopage,

docs/quickstart/assets/democards_workflow.png

@@ -6,116 +6,124 @@ This section describes how you can set up your demos easily in _five lines of co
 
 The rules of demo management are super simple:
 
-* you need one demo page to hold all the demo files
-* a demo page has several demo sections
+* you need one demo page (folder) to hold all the demo files
+* a demo page has several demo sections (subfolders)
 * a demo section either
     * has other demo sections as nested subsections, or,
-    * has the demo files
+    * has the demo files (`.md`, `.jl`)
 
 In the following example:
 
-* we have one demo page: "quickstart" ---> The current page you're looking at
-* "quickstart" has one demo section: "usage example"
-* "usage example" has two demo subsections: "basics" and "julia_demos"
-  * "basics" section holds all markdown demos
-  * "julia_demos" section holds all julia demos
-* "assets" folders are ignored by `DemoCards.jl`
-* "index.md" is where all demo cards are organized in (aka page template)
-* "config.json" are configuration files (there're many)
+* we have one demo page: `"quickstart"` ---> The current page you're looking at
+* `"quickstart"` has one demo section: `"usage example"`
+* `"usage example"` has two demo subsections: `"basics"` and `"julia_demos"`
+  * `"basics"` section holds all markdown demos
+  * `"julia_demos"` section holds all julia demos
+* `"assets"` folders are ignored by `DemoCards.jl`
+* `"index.md"` is where all demo cards are organized in (aka page template)
+* `"config.json"` are configuration files (there are many of them!)
 
 ```text
 docs/quickstart
+├── config.json
 ├── index.md
 └── usage_example
     ├── basics
     │   ├── assets
     │   ├── config.json
     │   ├── configure_card.md
     │   ├── configure_sec_and_page.md
+    │   ├── hidden_card.jl
+    │   ├── hide_your_card_from_index.md
     │   └── simple_markdown_demo.md
     ├── config.json
     └── julia_demos
         ├── 1.julia_demo.jl
         ├── 2.cover_on_the_fly.jl
-        └── assets
+        ├── assets
+        └── config.json
 ```
 
-```@setup simplest_demopage
-using DemoCards
-using DemoCards: DemoPage
-```
-
-_Democards_ can read the demo structure from your folder structure:
+This is the core idea, as long as you organize your folder in a structural way, DemoCards will read
+and process your demos to map your folder structure.
 
 ```@repl simplest_demopage
-cd("../../../..") do
-    DemoPage("docs/quickstart")
+using DemoCards
+cd(pkgdir(DemoCards)) do
+    DemoCards.DemoPage("docs/quickstart")
 end
 ```
 
 ## Deploy your demo page
 
-Deployment is also very simple:
+![democards workflow](assets/democards_workflow.png)
+
+The above image is the workflow of `DemoCards`. The deployment would be pretty easy:
 
-1. load a theme using `cardtheme`
-2. create a demopage using `makedemos`
-3. pass the results to `Documenter.jl`
-4. postprocess demos generated by Documenter
+1. pass your demos to `makedemos`, so that they're preprocessed before passing into `Documenter.jl`
+2. generate the entire documentation using `Documenter.makedocs`
+3. post process the generated demos using callbacks.
 
 ```julia
-# 1. generate a DemoCard theme
-templates, theme = cardtheme("grid")
+# 1. generate demo files
+demopage, postprocess_cb, demo_assets = makedemos("demos") # this is the relative path to docs/
 
-# 2. generate demo files
-demopage, postprocess_cb = makedemos("demos", templates) # relative path to docs/
+# if there are generated css assets, pass it to Documenter.HTML
+assets = []
+isnothing(demo_assets) || (push!(assets, demo_assets))
 
-# 3. normal Documenter usage
-format = Documenter.HTML(assets = [theme, ])
+# 2. normal Documenter usage
+format = Documenter.HTML(assets = assets)
 makedocs(format = format,
          pages = [
             "Home" => "index.md",
             demopage,
          ],
          sitename = "Awesome demos")
 
-# 4. postprocess after makedocs
+# 3. postprocess after makedocs
 postprocess_cb()
 ```
 
+In this example, there are three returned objects from `makedemos`:
+
+* `demopage`: this is the relative path to the generated demos (typically in `src/democards`), you
+  can pass it to `makedocs`'s `pages`.
+* `postprocess_cb`: this is the callback function that you'll need to call after `makedocs`.
+* `demo_assets`: if available, it is the path to css file which you could pass to `Documenter.HTML`
+  as style assets. If no theme is configured for your page, it will be `nothing.
 
 After it's set up, you can now focus on contributing more demos and leave
 other works to `DemoCards.jl`.
 
-Here's the generated democards! You can read it one by one to get how things are managed in `DemoCards.jl`.
+🎉 The following example grids are generated using `DemoCards`! You can read them one by one for
+advanced configuration helps. Or you could read the [Concepts](@ref concepts) page first to get
+better understanding about the DemoCards type system.
 
 ---
 
 {{{democards}}}
 
 ---
 
-Actually, this exact page you're reading is generated by `DemoCards.jl`, which we call _the index
-page_ of demos. An index page always have cover images, that could sometimes be undesired. In this
-case, you could choose to not generate the index page, and use the Documenter's sidebar for
-navigation. For example, the "Theme: None" section in "Theme Gallery" is generated by the following
-setup:
+The page you are reading right now is the generated index page of demos. An index page always have
+cover images for the demos. An index page is only generated if you configure the `theme` option in
+your page config file (e.g., `docs/quickstart/config.json`):
 
-```julia
-# 1. generate demo files
-# If you don't pass the templates for index page, then it won't be generated
-demopage, postprocess_cb = makedemos("demos")
+```json
+{
+    "theme": "grid"
+}
+```
 
-# 2. normal Documenter usage
-makedocs(format = Documenter.HTML(),
-         pages = [
-            "Home" => "index.md",
-            demopage,
-         ],
-         sitename = "Awesome demos")
+There are three themes available now:
 
-# 3. postprocess after makedocs
-postprocess_cb()
-```
+* `"nothing"`(default): index page and associated assets will not be generated, instead, it will use
+  the sidebar generated by Documenter.jl to navigate through pages. This is the default option when
+  you doesn't configure `"theme"`.
+* `"grid"` and `"list"`: an index page and associated cover images are generated
+
+Please check the "Theme Gallery" part for a preview of these themes.
 
 ## What DemoCards.jl does
 
@@ -124,8 +132,9 @@ The pipeline of [`makedemos`](@ref DemoCards.makedemos) is:
 1. analyze the structure of your demo folder and extracts supplementary configuration information
 2. copy "`assets`" folder without processing
 3. preprocess demo files and save it
-4. process and save cover images
-5. generate a postprocessing callback function
+4. (optional) process and save cover images
+5. (optional) generate index page
+6. generate a postprocessing callback function
 
 Since all files are generated to `docs/src`, the next step is to leave everything else
 to `Documenter.jl` 💯
@@ -140,9 +149,8 @@ to `Documenter.jl` 💯
 For advanced usage of `DemoCards.jl`, you need to understand the core [concepts](@ref concepts) of it.
 
 !!! warning
-
     Currently, there's no guarantee that this function works for untypical
-    documentation folder structure. By the name **typical**, it is:
+    documentation folder structure. By the word **typical**, it is:
 
     ```julia
     .

docs/quickstart/index.md

@@ -7,35 +7,50 @@ date: 2020-09-13
 description: This demo show you how to pass additional meta info of card to DemoCards.jl
 ---
 
-Besides the meta info extracted from your demo contents, `DemoCards.jl` also
-reads the YAML format frontmatter, for example, this demo uses the following
-frontmatter:
+This page is generated from a markdown file. In `DemoCards.jl`'s type system, it is called
+[`MarkdownDemoCard`](@ref DemoCards.MarkdownDemoCard) whose contents are written in the markdown
+format. 
+
+The markdown files are almost directly passed to `Documenter.jl`, check the
+[syntax of Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/man/syntax/)
+if you are unfamiliar with the Julia flavor markdown syntax.
+
+DemoCards extracts potential information from the file to build the index page, e.g., name, title,
+reference id, cover image file/URL. If that's not available, then you would need to configure them
+by adding a [YAML format front matter](https://jekyllrb.com/docs/front-matter/).
+
+Supported YAML keywords are list as follows:
+
+* `cover`: an URL or a relative path to the cover image. If not configured, it would use the DemoCard logo.
+* `description`: a multi-line description to this file, will be displayed when the demo card is hovered.
+* `id`: specify the `id` tag for cross-references.
+* `title`: one-line description to this file, will be displayed under the cover image.
+* `author`: author name. If there are multiple authors, split them with semicolon `;`.
+* `date`: any string contents that can be passed to `Dates.DateTime`.
+* `hidden`: whether this card is shown in the layout of index page.
+
+!!! tip
+    All these YAML configs are optional. If specified, it has higher priority over the meta info
+    extracted from the demo contents. For example, if you don't like the inferred demo title, then
+    specify one explicitly in the YAML frontmatter.
+
+Of course, you have to make sure the `---` flag shows at the first line of the markdown file,
+otherwise DemoCards would just read them as normal contents.
+
+For example, the markdown file of this page uses the following frontmatter:
 
 ```markdown
 ---
 title: Configure your card
-cover: assets/democards.png
+cover: assets/logo.svg
 id: configure_your_card
 author: Johnny Chen
 date: 2020-09-13
 description: This demo show you how to pass additional meta info of card to DemoCards.jl
-
 ---
-```
-
-!!! tip
-    All these YAML configs are optional. If specified, it has higher priority over the meta info
-    extracted from the demo contents. For example, if you don't like the inferred demo title, then
-    specify one explicitly in the YAML frontmatter.
 
-    Of course, you have to make sure the `---` flag shows at the first line of the markdown file,
-    otherwise DemoCards would just read them as normal contents.
-
-The rules are simple:
+```
 
-* `author` and `date` badges will only be added if you configure them.
-* If there are multiple authors, they could be splitted by semicolon `;`. For example, `author:
-  Jane Doe; John Roe` would generate two author badges.
-* there are two valid `cover` options:
-  * a local file specified by relative path to the current file, or,
-  * an image file specified by http(s) URL.
+As you can see, if configured, there will be badges for `author` and `date` info. If there are
+multiple authors, they could be splitted by semicolon `;`. For example, `author: Jane Doe; John Roe`
+would generate two author badges.

docs/quickstart/usage_example/basics/configure_card.md

@@ -3,7 +3,7 @@ title: Configure your section and page
 cover: assets/logo.svg
 ---
 
-This demo shows you how to manipulate your demo sections.
+This demo shows you how to configure your demo page and sections.
 
 By default, a demo section takes the folder name as its section title, and it
 takes the file orders as its card orders, which can be unsatisfying in many cases.
@@ -33,8 +33,8 @@ page. For example:
 }
 ```
 
-If not specified, `template` is `"index.md"` if that exists, otherwise, it is a clean minimal
-template generated by DemoCards.
+If `template` is not specified, `"index.md"` will be used if available, otherwise, it will use a
+blank template generated by DemoCards.
 
 There are three possible options for `theme`:
 

docs/quickstart/usage_example/basics/configure_sec_and_page.md

@@ -1,8 +1,11 @@
 ---
 title: Hide your card from page index layout
 description: This demo shows you how to hide your card in page layout.
+hidden: false
 ---
 
+[![](https://img.shields.io/badge/jump%20to-a%20hidden%20demo-blue)](@ref hidden_card)
+
 There are cases that you want to hide one card in the generated page layout and only provide the
 entrance via reflink. For example, you have multiple version of demos and you only want to set the
 latest one as the default and provide legacy versions as reflink in the latest page.