From e64c1b90bedbe2683499256c3ba22442259e16f9 Mon Sep 17 00:00:00 2001 From: weru Date: Tue, 1 Feb 2022 01:15:05 +0300 Subject: document change dafdedb #73 Signed-off-by: weru --- exampleSite/config/_default/params.toml | 4 +- .../content/docs/compose/organize-content.md | 10 +- exampleSite/content/tutorials/_index.md | 18 + exampleSite/content/tutorials/example/_index.md | 8 + exampleSite/content/tutorials/example/mermaid.md | 375 +++++++++++++++++++++ 5 files changed, 413 insertions(+), 2 deletions(-) create mode 100644 exampleSite/content/tutorials/_index.md create mode 100644 exampleSite/content/tutorials/example/_index.md create mode 100644 exampleSite/content/tutorials/example/mermaid.md diff --git a/exampleSite/config/_default/params.toml b/exampleSite/config/_default/params.toml index 791d741..dac2e04 100644 --- a/exampleSite/config/_default/params.toml +++ b/exampleSite/config/_default/params.toml @@ -1,4 +1,6 @@ -mainSections = ["posts"] # use it for blog page section +mainSections = ["posts"] # use it for blog page section +# use the setting below to set multiple docs directories. +# docSections = ["docs", "tutorials"] uniqueHomePage = true # change to false to add sidebar to homepage diff --git a/exampleSite/content/docs/compose/organize-content.md b/exampleSite/content/docs/compose/organize-content.md index d4b0db7..0e130d0 100644 --- a/exampleSite/content/docs/compose/organize-content.md +++ b/exampleSite/content/docs/compose/organize-content.md @@ -7,7 +7,15 @@ This theme is primarily meant for documentation. #### Documentation -All your documentation content should be authored within the `docs` directory. +By default, the theme will look for all your documentation content within the `docs` directory. + +However, if you would like to have your docs content across multiple directories, please list those directories inside `config/_default/params.toml` under `docSections` like so: + +``` +... +docSections = ["docs", "tutorials"] +... +``` Unlike other regular pages, the documentation pages will have a left sidebar. This sidebar will list links to all the pages in the documentation pages. Beneath each link, there will be a collapsible list of __table of contents'__ links. These nested lists will unfold automatically on the active/current page. diff --git a/exampleSite/content/tutorials/_index.md b/exampleSite/content/tutorials/_index.md new file mode 100644 index 0000000..cde0c19 --- /dev/null +++ b/exampleSite/content/tutorials/_index.md @@ -0,0 +1,18 @@ +--- +title: "Tutorials' Docs" +weight: 1 +--- + +These docs consists of two parts: + +1. Hugo Compose Themes docs +2. Hugo Clarity Theme docs. + +Please note that the features listed under each theme are independent of each other. That is to say, some features may only be found in one theme and not in both. + + + +{{< button "./compose/" "Compose Theme Docs" "mb-1" >}} + +{{< button "./clarity/" "Clarity Theme Docs" >}} + diff --git a/exampleSite/content/tutorials/example/_index.md b/exampleSite/content/tutorials/example/_index.md new file mode 100644 index 0000000..7d837d0 --- /dev/null +++ b/exampleSite/content/tutorials/example/_index.md @@ -0,0 +1,8 @@ +--- +title: "Compose Docs" +weight: 1 +--- + +Welcome to the Compose theme user guide! This guide shows you how to get started creating technical documentation sites using Compose, including site customization and how to use Compose's blocks and templates. + +{{< button "./install-theme/" "Get started now" >}} diff --git a/exampleSite/content/tutorials/example/mermaid.md b/exampleSite/content/tutorials/example/mermaid.md new file mode 100644 index 0000000..306c79a --- /dev/null +++ b/exampleSite/content/tutorials/example/mermaid.md @@ -0,0 +1,375 @@ +--- +title: "Mermaid" +weight: 8 +description: "Generate diagrams, flowcharts, and piecharts from text in a similar manner as markdown." +--- + +[Mermaid](https://mermaidjs.github.io/) is library that helps you generate diagrams, flowcharts, and piecharts from text in a similar manner as markdown. + +With compose theme, you can use mermaid using a custom shortcode as follows: + +### Sequence Diagrams + +**Syntax** + +```tpl +{{}} +sequenceDiagram + participant Alice + participant Bob + Alice->>John: Hello John, how are you? + loop Healthcheck + John->>John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail... + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +{{}} +``` + +**Result** + +{{< mermaid >}} +sequenceDiagram + participant Alice + participant Bob + Alice->>John: Hello John, how are you? + loop Healthcheck + John->>John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail... + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +{{< /mermaid >}} + +### Flow Charts + +**Syntax** + +```tpl +{{}} +flowchart TB + c1-->a2 + subgraph one + a1-->a2 + end + subgraph two + b1-->b2 + end + subgraph three + c1-->c2 + end + one --> two + three --> two + two --> c2 +{{}} +``` +**Result** + +{{< mermaid >}} +flowchart TB + c1-->a2 + subgraph one + a1-->a2 + end + subgraph two + b1-->b2 + end + subgraph three + c1-->c2 + end + one --> two + three --> two + two --> c2 +{{< /mermaid >}} + +### Graphs + +**Syntax** + +```tpl +{{}} +graph TB + sq[Square shape] --> ci((Circle shape)) + + subgraph A + od>Odd shape]-- Two line
edge comment --> ro + di{Diamond with
line break} -.-> ro(Rounded
square
shape) + di==>ro2(Rounded square shape) + end + + %% Notice that no text in shape are added here instead that is appended further down + e --> od3>Really long text with linebreak
in an Odd shape] + + %% Comments after double percent signs + e((Inner / circle
and some odd
special characters)) --> f(,.?!+-*ز) + + cyr[Cyrillic]-->cyr2((Circle shape Начало)); + + classDef green fill:#9f6,stroke:#333,stroke-width:2px; + classDef orange fill:#f96,stroke:#333,stroke-width:4px; + class sq,e green + class di orange +{{}} +``` + +**Result** + +{{< mermaid >}} +graph TB + sq[Square shape] --> ci((Circle shape)) + + subgraph A + od>Odd shape]-- Two line
edge comment --> ro + di{Diamond with
line break} -.-> ro(Rounded
square
shape) + di==>ro2(Rounded square shape) + end + + %% Notice that no text in shape are added here instead that is appended further down + e --> od3>Really long text with linebreak
in an Odd shape] + + %% Comments after double percent signs + e((Inner / circle
and some odd
special characters)) --> f(,.?!+-*ز) + + cyr[Cyrillic]-->cyr2((Circle shape Начало)); + + classDef green fill:#9f6,stroke:#333,stroke-width:2px; + classDef orange fill:#f96,stroke:#333,stroke-width:4px; + class sq,e green + class di orange +{{< /mermaid >}} + +**Syntax** + +```tpl +{{}} +graph LR + A[Hard edge] -->|Link text| B(Round edge) + B --> C{Decision} + C -->|One| D[Result one] + C -->|Two| E[Result two] +{{}} +``` + +**Result** + +{{< mermaid >}} +graph LR + A[Hard edge] -->|Link text| B(Round edge) + B --> C{Decision} + C -->|One| D[Result one] + C -->|Two| E[Result two] +{{< /mermaid >}} + +### Class Diagram + +{{< mermaid >}} +classDiagram + Animal <|-- Duck + Animal <|-- Fish + Animal <|-- Zebra + Animal : +int age + Animal : +String gender + Animal: +isMammal() + Animal: +mate() + class Duck{ + +String beakColor + +swim() + +quack() + } + class Fish{ + -int sizeInFeet + -canEat() + } + class Zebra{ + +bool is_wild + +run() + } +{{< /mermaid >}} + + +### State Diagram + +{{< mermaid >}} +stateDiagram-v2 + [*] --> Active + + state Active { + [*] --> NumLockOff + NumLockOff --> NumLockOn : EvNumLockPressed + NumLockOn --> NumLockOff : EvNumLockPressed + -- + [*] --> CapsLockOff + CapsLockOff --> CapsLockOn : EvCapsLockPressed + CapsLockOn --> CapsLockOff : EvCapsLockPressed + -- + [*] --> ScrollLockOff + ScrollLockOff --> ScrollLockOn : EvScrollLockPressed + ScrollLockOn --> ScrollLockOff : EvScrollLockPressed + } +{{< /mermaid >}} + +{{< mermaid >}} +stateDiagram-v2 + State1: The state with a note + note right of State1 + Important information! You can write + notes. + end note + State1 --> State2 + note left of State2 : This is the note to the left. +{{< /mermaid >}} + +### Relationship Diagrams + +**Syntax** + +```tpl +{{}} +erDiagram + CUSTOMER ||--o{ ORDER : places + ORDER ||--|{ LINE-ITEM : contains + CUSTOMER }|..|{ DELIVERY-ADDRESS : uses +{{}} +``` + +**Result** + +{{< mermaid >}} +erDiagram + CUSTOMER ||--o{ ORDER : places + ORDER ||--|{ LINE-ITEM : contains + CUSTOMER }|..|{ DELIVERY-ADDRESS : uses +{{< /mermaid >}} + +### User Journey + +**Syntax** + +```tpl +{{}} +journey + title My working day + section Go to work + Make tea: 5: Me + Go upstairs: 3: Me + Do work: 1: Me, Cat + section Go home + Go downstairs: 5: Me + Sit down: 5: Me +{{}} + +``` + +**Result** + +{{< mermaid >}} +journey + title My working day + section Go to work + Make tea: 5: Me + Go upstairs: 3: Me + Do work: 1: Me, Cat + section Go home + Go downstairs: 5: Me + Sit down: 5: Me +{{< /mermaid >}} + +### Gantt + +**Syntax** + +```tpl +{{}} +gantt + dateFormat YYYY-MM-DD + title Adding GANTT diagram functionality to mermaid + excludes weekends + %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".) + + section A section + Completed task :done, des1, 2014-01-06,2014-01-08 + Active task :active, des2, 2014-01-09, 3d + Future task : des3, after des2, 5d + Future task2 : des4, after des3, 5d + + section Critical tasks + Completed task in the critical line :crit, done, 2014-01-06,24h + Implement parser and jison :crit, done, after des1, 2d + Create tests for parser :crit, active, 3d + Future task in critical line :crit, 5d + Create tests for renderer :2d + Add to mermaid :1d + + section Documentation + Describe gantt syntax :active, a1, after des1, 3d + Add gantt diagram to demo page :after a1 , 20h + Add another diagram to demo page :doc1, after a1 , 48h + + section Last section + Describe gantt syntax :after doc1, 3d + Add gantt diagram to demo page :20h + Add another diagram to demo page :48h +{{}} +``` + +**Result** + +{{< mermaid >}} +gantt + dateFormat YYYY-MM-DD + title Adding GANTT diagram functionality to mermaid + excludes weekends + %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".) + + section A section + Completed task :done, des1, 2014-01-06,2014-01-08 + Active task :active, des2, 2014-01-09, 3d + Future task : des3, after des2, 5d + Future task2 : des4, after des3, 5d + + section Critical tasks + Completed task in the critical line :crit, done, 2014-01-06,24h + Implement parser and jison :crit, done, after des1, 2d + Create tests for parser :crit, active, 3d + Future task in critical line :crit, 5d + Create tests for renderer :2d + Add to mermaid :1d + + section Documentation + Describe gantt syntax :active, a1, after des1, 3d + Add gantt diagram to demo page :after a1 , 20h + Add another diagram to demo page :doc1, after a1 , 48h + + section Last section + Describe gantt syntax :after doc1, 3d + Add gantt diagram to demo page :20h + Add another diagram to demo page :48h +{{< /mermaid >}} + +### Pie Chart + +```tpl +{{}} +pie + title Key elements in Product X + "Calcium" : 42.96 + "Potassium" : 50.05 + "Magnesium" : 10.01 + "Iron" : 5 +{{}} + +``` + +**Result** + +{{< mermaid >}} +pie + title Key elements in Product X + "Calcium" : 42.96 + "Potassium" : 50.05 + "Magnesium" : 10.01 + "Iron" : 5 +{{< /mermaid >}} -- cgit v1.2.3