Merge pull request #375 from Minimum-CD/use-docsy

Switch to Docsy

.github/workflows/ci.yml

@@ -1,6 +1,3 @@
-# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
 name: Node.js CI
 
 on:

.prettierignore

@@ -0,0 +1,19 @@
+public/
+node_modules/
+.cache
+.history
+dist
+coverage
+docs/app
+__mocks__
+userguide/
+.release-please-manifest.json
+CHANGELOG.md
+.vscode/
+assets/js/drawio.js
+assets/js/markmap.js
+assets/js/mermaid.js
+assets/js/plantuml.js
+assets/js/base.js
+static/js/deflate.js
+static/js/swagger*.js

.prettierrc

@@ -0,0 +1,22 @@
+{
+  "plugins": [
+    "prettier-plugin-go-template"
+  ],
+  "trailingComma": "es5",
+  "tabWidth": 2,
+  "semi": false,
+  "singleQuote": true,
+  "bracketSpacing": true,
+  "editorconfig": true,
+  "htmlWhitespaceSensitivity": "ignore",
+  "overrides": [
+    {
+      "files": [
+        "*.html"
+      ],
+      "options": {
+        "parser": "go-template"
+      }
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "cSpell.words": [
+        "isset",
+        "pygments"
+    ]
+}

archetypes/default.md

@@ -1,6 +1,5 @@
----
-title: "{{ replace .Name "-" " " | title }}"
-date: {{ .Date }}
-draft: true
----
-
++++
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+date = {{ .Date }}
+draft = true
++++

content/ExperienceReports/_index.md

@@ -1,7 +1,12 @@
 ---
 title: Community Experiences
+linkTitle: "Experiences"
 description: CD in the real world
 weight: 5
+type: docs
+menu:
+  main:
+    weight: 20
 ---
 
 ## CD in the Real World
@@ -18,13 +23,13 @@ It's true, some people still think CD is just tools. Here are some reports from
 
 ## Feedback
 
-{{% panel footer="Dave Farley, Author: Continuous Delivery" %}}
+{{% card footer="Dave Farley, Author: Continuous Delivery" %}}
 MinimumCD is a fantastic way to get to the meat of CD quickly. It's a clear, focused, no-holds-barred statement of what it takes to achieve CD. This matters because CD works, and it works better than any other way of delivering software that anyone has found so far.
 
 If you aren't practicing CD in the way that MinimumCD describes it, then you are building worse software more slowly. The trouble is, CD is difficult to adopt. MinimumCD cuts through distracting or confusing complications. If you can do what MinimumCD says, you will be doing a better job. It gives us a clear, simple focus on the essentials of CD that can help teams to understand what really matters to build better software faster.
-{{% /panel %}}
+{{% /card %}}
 
 ## MinimumCD in the Media
 
-- [CodingBlocks Podcast, February 27, 2022](https://www.codingblocks.net/podcast/minimum-viable-continuous-delivery/): The host discuss their impressions of the project
+- [CodingBlocks Podcast, February 27, 2022](https://www.codingblocks.net/podcast/minimum-viable-continuous-delivery/): The hosts discuss their impressions of the project
 - [Tiny DevOps #21: Minimum Viable CD](https://jhall.io/archive/2021/11/30/minimum-viable-continuous-delivery/): Jonathan Hall talks to one of the core team about the goals of the project

content/FAQ/_index.md

@@ -1,8 +1,12 @@
 ---
 title: Frequent Questions
-description: FAQ
+linkTitle: "FAQ"
+description: 
 weight: 5
-draft: false
+type: docs
+menu:
+  main:
+    weight: 99
 ---
 
 ## Why does this exist?
@@ -57,7 +61,7 @@ config](https://12factor.net/config) definitions where "config" is environment s
 
 Central to CD is that we are validating the delivered artifact with the pipeline. It is built once and deployed to all
 environments. A common anti-pattern is building an artifact for each environment. This is why trunk-based development is
-so important. More can be found [here](../minimumcd/immutable/).
+so important. More can be found [here](/minimumcd/immutable/).
 
 ## What do we mean by "definition of deployable"?
 

content/Journey/_index.md

@@ -1,8 +1,13 @@
 ---
 title: Starting the Journey
+linkTitle: "Starting Out"
 description: Suggested improvement paths
 weight: 1
 draft: false
+type: docs
+menu:
+  main:
+    weight: 20
 ---
 
 So, where do we start? It's a bad idea to go from "we can't safely commit changes to the trunk" to "deploy every change to production immediately" in one step. It's a journey that requires methodically solving problems in the context of your organization. Here we will discuss some of the common challenges that frequently need to be overcome.
@@ -27,24 +32,26 @@ You may have some others on the list that as you start implementing will come in
 
 Every process we add needs to add value. There's obvious value in doing performance testing unless we are demanding performance at a level that isn't required for the use case. However, before we define CAB documentation as required for "deployable", why does that process exist? One common reason for that meeting is a compliance rule for "two sets of eyes on every change". However, that can be validated by automation without the need to bundle changes and wait for a meeting.
 
-{{%alert info%}}
+{{% alert %}}
 We wanted to investigate the impact of change approval processes on software delivery performance. Thus, we asked about four possible scenarios:
 
 - All production changes must be approved by an external body (such as a manager or CAB).
 - Only high-risk changes, such as database changes, require approval.
 - We rely on peer review to manage changes.
 - We have no change approval process.
 
-The results were surprising. We found that approval only for high-risk changes was not correlated with software delivery performance. Teams that reported no approval process or used peer review achieved higher software delivery performance. Finally, teams that required approval by an external body achieved lower performance.
-{{%/alert%}}
+The results were surprising. We found that approval only for high-risk changes was not correlated with software delivery
+performance. Teams that reported no approval process or used peer review achieved higher software delivery performance.
+Finally, teams that required approval by an external body achieved lower performance.
 
-Excerpt from *Accelerate* by Nicole Forsgren Ph.D., Jez Humble & Gene Kim
+__-- *Accelerate* by Nicole Forsgren Ph.D., Jez Humble & Gene Kim__
+{{% /alert %}}
 
 ## Solving the Challenge of CI
 
 The first challenge for the team is [continuous integration](https://www.martinfowler.com/articles/continuousIntegration.html). CD requires CI and CI is very effective at uncovering most of the problems many teams have that impact quality. Martin Fowler has an [excellent blog post on introducing CI](https://www.martinfowler.com/articles/continuousIntegration.html#IntroducingContinuousIntegration) into the workflow. Over the years, we've seen many common problems that teams have.
 
-You may find more. Notice that tooling is rarely the problem. Always, "why can't we deliver working changes to the trunk today?", is the roadmap of problems to solve.  
+You may find more. Notice that tooling is rarely the problem. Always, "Why can't we deliver working changes to the trunk today?", is the roadmap of problems to solve.  
 
 ### Code review takes too long / has too many approvers
 
@@ -68,7 +75,7 @@ Teams are not good at testing initially for the same reason they aren't good at
 
 ### Individual tasks are too big
 
-CI means we are integrating partially completed features continuously. TDD helps us learn how to decompose tasks into very small, releasable changes that do not break existing behaviors. However, the initial habit is often to wait to integrate changes until they are "complete". This results in large change-sets that are more difficult to code review. This makes code review take more time, requires more re-work, and reduces the ability of the reviewer to spot problems. [Evolutionary coding methods](../minimumcd/ci/#recommended-practices) allows the release of incomplete features until they are ready and allow us to drive down the size of changes. By focusing as a team to decompose tasks into hours of work rather than days and using engineering techniques to control release, we have improved clarity, smaller change-sets, and higher quality.
+CI means we are integrating partially completed features continuously. TDD helps us learn how to decompose tasks into very small, releasable changes that do not break existing behaviors. However, the initial habit is often to wait to integrate changes until they are "complete". This results in large changesets that are more difficult to code review. This makes code review take more time, requires more re-work, and reduces the ability of the reviewer to spot problems. [Evolutionary [coding methods](/minimumcd/ci/#recommended-practices) allow the release of incomplete features until they are ready and allow us to drive down the size of changes. By focusing as a team to decompose tasks into hours of work rather than days and using engineering techniques to control release, we have improved clarity, smaller change-sets, and higher quality.
 
 ### Stories are too big & lack testable acceptance criteria
 

content/MinimumCD/AppConfig/_index.md

@@ -3,4 +3,5 @@ title: Application Configuration
 description: Application configuration deploys with artifact
 weight: 5
 draft: true
+type: docs
 ---

content/MinimumCD/CI/_index.md

@@ -2,6 +2,7 @@
 title: Continuous Integration
 description: Start here
 weight: 2
+type: docs
 ---
 
 ## Definition

content/MinimumCD/Deployable/_index.md

@@ -3,5 +3,6 @@ title: Definition of Deployable
 description: Pipeline artifacts always meet the organization's definition of deployable
 weight: 5
 draft: true
+type: docs
 ---
 

content/MinimumCD/Deterministic/_index.md

@@ -3,4 +3,5 @@ title: Deterministic Pipeline
 description: The pipeline decides the releasability of changes
 weight: 5
 draft: true
+type: docs
 ---

content/MinimumCD/Immutable/_index.md

@@ -2,6 +2,7 @@
 title: Immutable Artifact
 description: No human changes after commit.
 weight: 5
+type: docs
 ---
 
 Central to CD is that we are validating the artifact with the pipeline. It is built once and deployed to all environments. A common anti-pattern is building an artifact for each environment. The pipeline should generate immutable, versioned artifacts.

content/MinimumCD/ProdLike/_index.md

@@ -2,6 +2,7 @@
 title: Prod-Like Test Environment
 description: Leveraging production-like test environments in your CI/CD pipeline enables reliable testing.
 weight: 5
+type: docs
 ---
 ## Definition
 

content/MinimumCD/Rollback/_index.md

@@ -3,5 +3,6 @@ title: Rollback On-demand
 description: Why these practices are important
 weight: 5
 draft: true
+type: docs
 ---
 

content/MinimumCD/SinglePath/_index.md

@@ -3,4 +3,5 @@ title: Only Path to Any Environment
 description: Build once, deploy everywhere
 weight: 5
 draft: true
+type: docs
 ---

content/MinimumCD/TBD/_index.md

@@ -2,13 +2,14 @@
 title: Trunk Based Development
 description: Death of merge hell
 weight: 1
+type: docs
 ---
 
 {{%alert info%}}
 
-"Trunk-based development has been shown to be a predictor of high performance in software development and delivery. It is characterized by fewer than three active branches in a code repository; branches and forks having very short lifetimes (e.g., less than a day) before being merged into master; and application teams rarely or never having "code lock" periods when no one can check in code or do pull requests due to merging conflicts, code freezes, or stabilization phases."
+"Trunk-based development has been shown to be a predictor of high performance in software development and delivery. It is characterized by fewer than three active branches in a code repository; branches and forks having very short lifetimes (e.g., less than a day) before being merged; and application teams rarely or never having "code lock" periods when no one can check in code or do pull requests due to merging conflicts, code freezes, or stabilization phases."
 
-{{%/alert%}}
+{{% /alert %}}
 
 Excerpt from *Accelerate* by Nicole Forsgren Ph.D., Jez Humble & Gene Kim
 
@@ -24,5 +25,5 @@ It is important to note that release branches are an intermediate step that some
 - **We must test**: TBD requires us to implement tests as part of the development process.
 - **Better teamwork**: We need to work more closely as a team. This has many positive impacts, not least we will be more focused on getting the team's highest priority done. We will stop starting and start finishing work.
 - **Better work definition**: Small changes require us to decompose the work into a level of detail that helps uncover things that lack clarity or do not make sense. This provides much earlier feedback on potential quality issues.
-- **Replaces process with engineering**: Instead of creating a process where we control the release of features with branches, we can control the release of features with engineering techniques called [evolutionary coding methods](../../minimumcd/ci/#recommended-practices). These techniques have additional benefits related to stability that cannot be found when replaced by process.
+- **Replaces process with engineering**: Instead of creating a process where we control the release of features with branches, we can control the release of features with engineering techniques called [evolutionary coding methods](/minimumcd/ci/#recommended-practices). These techniques have additional benefits related to stability that cannot be found when replaced by process.
 - **Reduces risk**: There are two risks with long-lived branches that happen frequently. First, the change will not integrate cleanly and the merge conflicts result in broken or lost features. Second, the branch will be abandoned. This is usually because of the first reason. Sometimes because all of the knowledge about what is in that branch resides in the mind of someone who decided to leave before it was integrated.

content/MinimumCD/_index.md

@@ -1,17 +1,21 @@
 ---
 title: Minimum Viable CD
-description: ""
+linkTitle: "Minimum CD"
+
+description: Problems to solve to improve your organization
 weight: 1
+type: docs
 ---
 
 
-{{% notice %}}
+{{% alert %}}
 "Continuous delivery improves both delivery performance and quality, and also helps improve culture and reduce burnout and deployment pain."
 
--- Accelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations
-{{% /notice %}}
+__-- *Accelerate* by Nicole Forsgren Ph.D., Jez Humble & Gene Kim__
+_
+{{% /alert %}}
 
-![MinimumCD](/images/minimumCD-logo-hex.png?height=150px)
+{{< figure src="/images/minimumCD-logo-hex.webp" alt="MinimumCD">}}
 
 We, [the undersigned](#signatories), believe that a minimal definition of continuous delivery (CD) is required to improve the flow of delivery and achieve the outcomes above. While our contexts may be different, there are universal practices common in all. By defining them we can:
 
@@ -35,13 +39,13 @@ The minimum activities required for CD are:
 - The [application
   pipeline](https://www.informit.com/articles/article.aspx?p=1621865&seqNum=2#:~:text=%EE%94%80Buy-,What%20Is%20a%20Deployment%20Pipeline%3F,-At%20an%20abstract)
   is the only way to deploy to any environment
-- The pipeline decides the releasability of changes, its verdict is [definitive](../faq/#why-should-the-pipeline-be-definitive-for-deploy)
-- Artifacts created by the pipeline always meet the organization's [definition of deployable](../faq/#what-do-we-mean-by-definition-of-deployable)
-- [Immutable artifact](../minimumcd/immutable/) (no human changes after commit)
+- The pipeline decides the releasability of changes, its verdict is [definitive](/faq/#why-should-the-pipeline-be-definitive-for-deploy)
+- Artifacts created by the pipeline always meet the organization's [definition of deployable](/faq/#what-do-we-mean-by-definition-of-deployable)
+- [Immutable artifact](/minimumcd/immutable/) (no human changes after commit)
 - All feature work stops when the pipeline is red
-- [Production-like test environment](../minimumcd/prodlike/)
+- [Production-like test environment](/minimumcd/prodlike/)
 - Rollback on-demand
-- [Application configuration](../faq/#what-is-application-configuration) deploys with artifact
+- [Application configuration](/faq/#what-is-application-configuration) deploys with artifact
 
 ## Continuous Integration
 
@@ -58,7 +62,7 @@ The minimum activities required for CI are:
 
 ## Trunk-based Development
 
-[Trunk-based development](../minimumcd/tbd) is the branching pattern required to meet the definition
+[Trunk-based development](/minimumcd/tbd) is the branching pattern required to meet the definition
 of CI. It prevents lost work, the risk of corruption that comes from merge conflict resolution, and also reduces movement
 waste that increases batch size.
 
@@ -72,11 +76,11 @@ The minimum activities required for TBD are:
 
 ## Why did we build this?
 
-For background on Minimum CD and answers to other common questions, please [read the FAQs](../faq).
+For background on Minimum CD and answers to other common questions, please [read the FAQs](/faq).
 
 ## Starting the Journey
 
-Questions on where to start? Check out some [recommendations](../journey).
+Questions on where to start? Check out some [recommendations](/journey).
 
 ## Contributing