Skip to content

Adds shortcodes to display architecture design docs (list and header)

Marc Saleiko requested to merge ms/design-docs-migration/adds-design-documents-list-shortcode into main

Why is this change being made?

Contributes to Move Architecture Blueprints to Public Handbook (#279 - closed)

We're about to move blueprints (now design documents) from the docs page (so gitlab project) to the public handbook. We want to use regular content files for this.

This MR adds two shortcodes that do the following:

  1. layouts/shortcodes/design-documents-list.html: Will be used to display a list of design docs from a given folder. The visual appearance is comparable with the current implementation.
  2. layouts/shortcodes/design-document-header.html: Will be used on every design document to display header information (same as in the current implementation). We chose not to use a new content type because this will introduce an additional round of refactoring and adding new templates, so we need this shortcode to add additional information to the design document (which is just a regular content site)

We also add two partials, which should be made available as shortcodes in the future, so they can be used in content sites as well:

  1. layouts/partials/gitlab/label.html: Overrides the partial from the docsy theme. The new implementation supports all functionality of labels (incl. scoped labels and color lookup from a data file) and the interface is compatible with the implementation of the theme (so it should not add any confusion). More details in the review comment.
  2. layouts/partials/gitlab/profile-links.html: Can be used to render a profile link or a list of profile links.

Please also check the comments in the frontmatter of the examples to understand test cases.

Screenshots

This is the design documents page with the list shortcode applied and three design documents. Ignore the not so correct label colors, these are for testing purposes with the color lookup precedence.

image

This is a design document page with some sample content (see the verify content below).

image

Verify locally

This is a bit tricky because there's no content available. I prepared some test files which you can download and add to the specified locations (content and paths in the collapsible area):

Click to expand and see test content

Test additional color:

Add this to data/label_colors.yml:

devops: "#E44D2A" # Matches scope only if no concrete match
devops::govern: "#000" # Concrete match
CRM: "#00ff00" # Matches label without scope

Main design docs page

Place in content/handbook/engineering/architecture/design-documents/_index.md

---
title: "Architecture Design Documents"
no_list: true
---

Introduction paragraph for Architecture Design Documents.

{{< design-documents-list folder="handbook/engineering/architecture/design-documents" >}}

Test doc 1

Place in content/handbook/engineering/architecture/design-documents/doc1/_index.md

---
title: "Replace `mail_room` email ingestion with scheduled Sidekiq jobs"
status: "rejected"
creation-date: "2023-06-05"
# Also support string authors
authors: "@msaleiko"
coach: "@stanhu"
# Also support string approvers
approvers: "@approver"
owning-stage: "devops::plan"
participating-stages: "~group::incubation"
toc_hide: true
---

{{< design-document-header >}}

## Excecutive summary

Occaecat nostrud exercitation reprehenderit veniam Lorem. Amet nostrud ut anim. Nulla qui commodo elit proident sunt do ipsum consectetur ipsum fugiat dolor proident. Occaecat sunt dolor pariatur adipisicing laboris elit minim non dolore sint nostrud. Adipisicing labore reprehenderit ad laborum. Incididunt cillum non culpa aliqua. Reprehenderit amet dolore esse reprehenderit culpa sint deserunt dolor occaecat est. Deserunt quis veniam dolor sunt excepteur est culpa amet reprehenderit deserunt ut sint voluptate do et.

Test doc 2

Place in content/handbook/engineering/architecture/design-documents/doc2/_index.md

---
title: "Test 2 design document"
status: "implemented"
creation-date: "2022-06-05"
# Support array authors
authors:
  - "@user1"
  - "@user2"
# Also support singular coach
coach: "@coach"
# Support array coaches
coaches:
  - "@supercoach"
  - "@othercoach"
# Support array approvers
approvers:
  - "@approver"
  - "@secondapprover"
# Support non scoped label owning stage
owning-stage: "CRM"
participating-stages: "~group::incubation"
toc_hide: true
---

{{< design-document-header >}}

Occaecat nostrud exercitation reprehenderit veniam Lorem. Amet nostrud ut anim. Nulla qui commodo elit proident sunt do ipsum consectetur ipsum fugiat dolor proident. Occaecat sunt dolor pariatur adipisicing laboris elit minim non dolore sint nostrud. Adipisicing labore reprehenderit ad laborum. Incididunt cillum non culpa aliqua. Reprehenderit amet dolore esse reprehenderit culpa sint deserunt dolor occaecat est. Deserunt quis veniam dolor sunt excepteur est culpa amet reprehenderit deserunt ut sint voluptate do et.

Test doc 3

Place in content/handbook/engineering/architecture/design-documents/doc3/_index.md

---
title: "Test 3 design document"
status: "proposed"
creation-date: "2024-06-05"
authors: 
  - "@darbyfrey"
coach: "@coachfromchicago"
# Support no approvers
approvers:
# Also support dris because it better reflects the rendered header
dris:
  - "@dri"
  - "@dri2"
owning-stage: "~devops::govern"
toc_hide: true
---

{{< design-document-header >}}

Content.

Author and Reviewer Checklist

Please verify the check list and ensure to tick them off before the MR is merged.

  • Provided a concise title for this Merge Request (MR)
  • Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
    • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
  • Assign reviewers for this MR to the correct Directly Responsible Individual/s (DRI)
    • If the DRI for the page/s being updated isn’t immediately clear, then assign it to one of the people listed in the Maintained by section on the page being edited
    • If your manager does not have merge rights, please ask someone to merge it AFTER it has been approved by your manager in #mr-buddies
    • The when to get approval handbook section explains the workflow in more detail
  • For transparency, share this MR with the audience that will be impacted.
    • Team: For changes that affect your direct team, share in your group Slack channel
    • Department: If the update affects your department, share the MR in your department Slack channel
    • Division: If the update affects your division, share the MR in your division Slack channel
    • Company: If the update affects all (or the majority of) GitLab team members, post an update in #whats-happening-at-gitlab linking to this MR

Commits

  • Adds shortcodes to display architecture design docs (list and header)
Edited by Marc Saleiko

Merge request reports