Quick Start

This section describes how you can set up your demos easily in five lines of codes.

Manage your demo files

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
• a demo section either
  • has other demo sections as nested subsections, or,
  • has the demo files

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)

docs/quickstart
├── index.md
└── usage_example
    ├── basics
    │   ├── assets
    │   ├── config.json
    │   ├── configure_card.md
    │   ├── configure_sec_and_page.md
    │   └── simple_markdown_demo.md
    ├── config.json
    └── julia_demos
        ├── 1.julia_demo.jl
        ├── 2.cover_on_the_fly.jl
        └── assets

Democards can read the demo structure from your folder structure:

julia> cd("../../../..") do
           DemoPage("docs/quickstart")
       end
DemoPage("docs/quickstart"):

# Quick Start
  ## Usage example
    ### Basics
      simple_markdown_demo.md
      configure_card.md
      configure_sec_and_page.md
    ### Julia demos
      1.julia_demo.jl
      2.cover_on_the_fly.jl

Deploy your demo page

Deployment is also very simple:

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. generate a DemoCard theme
templates, theme = cardtheme("grid")

# 2. generate demo files
demopage, postprocess_cb = makedemos("demos", templates) # relative path to docs/

# 3. normal Documenter usage
format = Documenter.HTML(edit_branch = "master",
                         assets = [theme, ])
makedocs(format = format,
         pages = [
            "Home" => "index.md",
            "Examples" => demopage,
         ],
         sitename = "Awesome demos")

# 4. postprocess after makedocs
postprocess_cb()

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 have a direct experience on how things are managed in DemoCards.jl.

Usage example

Basics

Demos can be written in typical markdown files with Documenter syntax, the only thing DemoCards does is to analyse the folder structure of your markdown files.

Julia demos

It also supports julia source codes (powered by Literate.jl). With this you can not only show typical mardown demo to readers but also provide a downloadable source code and an online notebook link. Another advantage is that you can generate demo assets on the fly(e.g., cover pages, artifacts), which is not an easy task for typical markdown demos using Documenter alone.

What DemoCards.jl does

The pipeline of 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

Since all files are generated to docs/src, the next step is to leave everything else to Documenter.jl 💯

For advanced usage of DemoCards.jl, you need to understand the core concepts of it.

.
├── Project.toml
├── docs/
│   ├── demos/ # manage your demos outside docs/src
│   ├── make.jl
│   ├── Project.toml
│   └── src/
├── src/
└── test/