Sync from github/github-well-architected-internal (main)

Source Repository: github/github-well-architected-internal

Source Branch: main

Source SHA: 19df7eb80cb63be9f9f42048ccf315e876108117

Author: well-architected-sync-bot[bot]

CONTRIBUTING.md

@@ -48,6 +48,7 @@ Thank you for contributing! We look forward to working with you. ❤️
 - :octocat: See [GitHub Well-Architected Framework overview] to understand the program and purpose.
 - 🗳️ We use [GitHub Flow] to manage changes. It is the most effective way to collaborate with all stakeholders on this project.
 - 🐙 [Issues] are used to **track work**, such as bug reports and feature requests. They are also used to keep track of ideas that may not yet be ready to work on.
+- :writing_hand: [Frontmatter and metadata](docs/contributing-learn.md) make content discoverable and publishable.
 - 🚢 [Pull requests] are the best way to collaborate on reviews.
 
 ---
@@ -131,39 +132,25 @@ Once you're ready to start, fork the repository and begin authoring. We **strong
 
 #### Create your article
 
-There are three options to create a new article:
-
-##### Option 1. Use the command `hugo new content` to create a new file (recommended in Codespaces)
-
-```shell
-# For recommendations:
-hugo new content library/{PILLAR}/recommendations/{ARTICLE-NAME}.md
-# For scenarios:
-hugo new content library/scenarios/{ARTICLE-NAME}.md
-```
-
-For example,
-
-```shell
-hugo new content library/productivity/recommendations/my-article.md
-```
+There are two options for creating a new article.
 
 > [!IMPORTANT]
-> When you use this method, you do not need to put `content/` in the command since Hugo considers it the root.
+> Hugo-based authoring workflows are deprecated in this repository. Rely on standard Markdown file creation and editing for article authoring. Hugo remains part of local preview/build behind the repository scripts.
 
-##### Option 2. Use a page bundle to create a new article with associated files like images
+##### Option 1. Use the template helper command (recommended)
 
-Add a folder (instead of one markdown file) at that location and bundle the files together. The format is:
+Run:
 
-```plaintext
-content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/index.md
-content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/image1.png
-content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/image2.png
+```shell
+# For recommendations:
+tools/new-content recommendation {PILLAR} {ARTICLE-NAME}
+# For scenarios:
+tools/new-content scenario {ARTICLE-NAME}
 ```
 
-##### Option 3. Copy/paste the template into a new file
+Replace `{PILLAR}` and `{ARTICLE-NAME}` with real values.
 
-Simply copy [`archetypes/default.md`] and paste it into:
+This command copies [`archetypes/default.md`] into the correct destination.
 
 For **recommendation** articles:
 
@@ -177,42 +164,30 @@ For **scenario** articles:
 content/library/scenarios/{ARTICLE-NAME}.md
 ```
 
-##### Writing Style:
+##### Option 2. Use a page bundle to create a new article with associated files like images
 
-- Always use sentence case
-- Keep your files tidy - no rogue spaces or characters, please
-- Use dashes for unordered lists (not `*`)
-- Use single spaces before and after headings, lists, and paragraphs
+Add a folder (instead of one markdown file) at that location and bundle the files together. The format is:
 
-#### Edit front-matter
+```plaintext
+content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/index.md
+content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/page1.md
+content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/assets/image1.png
+content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/assets/image2.png
+```
 
-Each article (written in markdown) should have front-matter at the top of the file. This front-matter should look like this:
+> [!WARNING]
+> Do not use `hugo new content` for new article creation in this repository.
 
-```yaml
----
-draft: true # Set to false when ready to publish
-title: 'Insert title here'
-publishDate: 2024-12-05 # Date the article is published
-
-# Add author details
-params:
-  authors:
-    [
-      { name: 'Mona', handle: 'octocat' },
-    ]
-
-# Classifications of the framework to drive key concepts, design principles, and architectural best practices
-pillars:
-  - placeholder
-  - placeholder
----
-```
+#### Writing style
 
-- When you are done with your article, set `draft: false` when you are ready to publish.
+- Always use sentence case
+- Keep your files tidy - no rogue spaces or characters, please
+- Use dashes for unordered lists (not `*`)
+- Use single spaces before and after headings, lists, and paragraphs
 
-- Set `publishDate` to the date the article is first merged to `main`. Do not change it on future revisions.
+#### Required frontmatter and metadata
 
-- All recommended values for all of these fields are described in [Taxonomies]. **Insert all that apply to your article. This is how your article will be discoverable!**
+Articles must include the required frontmatter fields described in [docs/contributing-learn.md](docs/contributing-learn.md). This is critical for the content to be processed and published correctly.
 
 ---
 
@@ -356,10 +331,10 @@ There are several primary types of contributions to this project:
 
 ### 📝 Content Library Article Submission(s)
 
-Contributions will typically author content articles under `/content/` folder. To start writing, we recommend reviewing these essential framework resources:
+Contributions typically involve authoring content articles under the `/content/` folder. To start writing, we recommend reviewing these essential framework resources:
 
 - [Framework Overview] - Learn about the WAF mission, vision, objectives, and five pillars
-- [Taxonomies](/docs/taxonomies.md) - Explore the design principles, areas, and other classifications
+- [Taxonomies] - Explore the design principles, areas, and other classifications
 
 **Inspiration for Content Library articles** comes from **Azure Architecture Center**. See the following example articles for your inspiration: 💡
 
@@ -426,7 +401,7 @@ See [Framework Overview] for details on each pillar.
 - Avoid unnecessary jargon
 - Include practical examples
 - Prefer GitHub Docs links to **Enterprise Cloud**: `https://docs.github.com/enterprise-cloud@latest` (unless the guidance is specific to GitHub Enterprise Server)
-- Use Hugo shortcodes to keep articles consistent (see `archetypes/default.md`):
+- Use repository shortcodes to keep articles consistent (see [`archetypes/default.md`]):
   - Further assistance: `{{% seeking-further-assistance-details %}}`
   - Related links: `{{% related-links-github-docs %}}`
 
@@ -488,7 +463,7 @@ Here are the checklists for code reviewers.
 
 ## Code of conduct
 
-By participating, you are expected to the GitHub Community [Code of Conduct].
+By participating, you are expected to follow the GitHub Community [Code of Conduct].
 
 ---
 

archetypes/default.md

@@ -1,72 +1,67 @@
 ---
 draft: false # Set to true to keep the page hidden
 title: 'Insert title here'
-publishDate: YYYY-MM-DD
-params:
+publishDate: 2006-01-02 # Example format placeholder; replace before merge
 
-# Add and remove authors as needed. Please reserve authorship for significant contributions, not edits and feedback.
+# Optional navigation metadata
+# weight: 1
+# prev: library/{PILLAR}/previous-page
+# next: library/{PILLAR}/next-page
 
-authors: [
-{name: "INSERT_NAME_1", handle: "INSERT_HANDLE_1"},
-{name: "INSERT_NAME_2", handle: "INSERT_HANDLE_2"},
-]
+params:
+  authors:
+    - name: "INSERT_NAME_1"
+      handle: "INSERT_HANDLE_1"
+    - name: "INSERT_NAME_2"
+      handle: "INSERT_HANDLE_2"
 
 # Classifications of the framework to drive key concepts, design principles, and architectural best practices
 
 pillars:
-
-- placeholder
-- placeholder
+  - placeholder
+  - placeholder
 
 # The areas of the GitHub adoption journey. Inspiration taken from docs.github.com
 
 areas:
-
-- placeholder
-- placeholder
+  - placeholder
+  - placeholder
 
 # Classifications of industries who may be at different stages of the customer journey.
 
 verticals:
-
-- placeholder
-- placeholder
+  - placeholder
+  - placeholder
 
 # Individuals in key roles on the customer journey, typically consisting of one or more administrators and the end-user community.
 
 personas:
-
-- placeholder
-- placeholder
+  - placeholder
+  - placeholder
 
 # Deployment options for GitHub Enterprise, including Cloud (GHEC), Server (GHES), and Hybrid.
 
 platform:
-
-- placeholder
-- placeholder
+  - placeholder
+  - placeholder
 
 # GitHub product functions designed to support every stage of development.
 
 features:
-
-- placeholder
-- placeholder
+  - placeholder
+  - placeholder
 
 # Deeper-level topics of the GitHub Platform and its features. They are most often interacted with by end-users.
 
 components:
-
-- placeholder
-- placeholder
+  - placeholder
+  - placeholder
 
 # Associated teams and other GitHub and Partner resources that can provide additional support.
 
 github:
-
-- placeholder
-- placeholder
-
+  - placeholder
+  - placeholder
 ---
 
 <!-- This disables the linting rule for multiple top-level headers -->

config/_default/hugo.yaml

@@ -4,20 +4,27 @@ languageCode: en-us
 title: GitHub Well-Architected
 enableInlineShortcodes: true   # https://imfing.github.io/hextra/docs/guide/shortcodes/icon
 enableGitInfo: true
+contentDir: content-processed
 
 # import hextra as module
 module:
   imports:
   - path: github.com/imfing/hextra
     version: v0.8.6
-  
+
 
 build:
   # cache busting for css changes
   cachebusters:
   - source: layouts/.*
     target: css
 
+# Cascade type: docs to all library pages so Hugo uses the docs layout (sidebar enabled)
+cascade:
+  - _target:
+      path: /library/**
+    type: docs
+
 markup:
   # allow raw html
   goldmark:
@@ -90,7 +97,7 @@ params:
   displayAuthorInfo: true
 
 frontmatter:
-  publishDate: 
+  publishDate:
       - publishDate
       - :filename
       - date
@@ -100,7 +107,7 @@ frontmatter:
   navbar:
     displayTitle: true
     displayLogo: true
-    logo: 
+    logo:
       path: media/github-mark.svg
       dark: media/github-mark-white.svg
       link: /

content/_index.md

@@ -1,6 +1,7 @@
 ---
 # SPDX-FileCopyrightText: GitHub and The Project Authors
 # SPDX-License-Identifier: MIT
+title: GitHub Well-Architected Framework
 description: The GitHub Well-Architected Framework is an open source-style, community-driven framework to curate the best way to deploy the GitHub platform.
 params:
   logosBlock: false

content/index.yml

@@ -0,0 +1,5 @@
+
+# SPDX-FileCopyrightText: GitHub and The Project Authors
+# SPDX-License-Identifier: MIT
+title: GitHub Well-Architected Framework
+description: The GitHub Well-Architected Framework is an open source-style, community-driven framework to curate the best way to deploy the GitHub platform.

content/library/_index.md

@@ -1,16 +1,7 @@
 ---
 # SPDX-FileCopyrightText: GitHub and The Project Authors
 # SPDX-License-Identifier: MIT
-title: 🔒 Application Security
+title: Overview
+linkTitle: Application Security
 weight: 5
-slug: application-security
 ---
-
-The **Application Security** pillar is about ensuring the security of your applications. It could include principles related to using GitHub's security features like Dependabot, security advisories, and code scanning.
-
-{{< cards >}}
-  {{< card link="quick-links" title="Quick Links" icon="sparkles" >}}
-  {{< card link="design-principles" title="Design Principles" icon="book-open" >}}
-  {{< card link="checklist" title="Assessment Checklist" icon="book-open" >}}
-  {{< card link="recommendations" title="Recommendations" icon="book-open" >}}
-{{< /cards >}}

content/library/application-security/_index.md

@@ -2,7 +2,7 @@
 # SPDX-FileCopyrightText: GitHub and The Project Authors
 # SPDX-License-Identifier: MIT
 title: Checklist for Application Security
-weight: 3
+weight: 4
 prev: library/application-security/design-principles
 next: library/application-security/recommendations
 ---

content/library/application-security/checklist.md

@@ -2,7 +2,7 @@
 # SPDX-FileCopyrightText: GitHub and The Project Authors
 # SPDX-License-Identifier: MIT
 title: Design Principles
-weight: 2
+weight: 3
 prev: library/application-security/quick-links
 next: library/application-security/checklist
 ---

content/library/application-security/design-principles.md

@@ -0,0 +1,5 @@
+title: Application Security
+description: Proactive guidelines for embedding security into every stage of development, from code scanning to compliance.
+weight: 5
+slug: application-security
+icon: ShieldLockIcon