reorganize docs to include architectural decisions

.github/CODEOWNERS

@@ -4,8 +4,8 @@
 # for details on how to update this file <3
 * @github/primer-rails-reviewers
 
-/docs/logo.md @dylanatsmith
-/docs/logo/**/* @dylanatsmith
+/docs/about/logo.md @dylanatsmith
+/docs/about/logo/**/* @dylanatsmith
 
 /lib/view_component/slotable.rb @blakewilliams
 /test/view_component/slotable_test.rb @blakewilliams

.github/workflows/lint.yml

@@ -60,7 +60,7 @@ jobs:
       - name: echo changed files
         run: |
           if [[ ! "${{needs.changedfiles.outputs.markdown}}" == *"CHANGELOG.md"* ]]; then
-            echo "::error file=CHANGELOG.md,line=1,col=1::Please make sure that you add a docs/CHANGELOG.md entry to describe the changes in this pull request."
+            echo "::error file=CHANGELOG.md,line=1,col=1::Please make sure that you add a docs/about/CHANGELOG.md entry to describe the changes in this pull request."
             exit 1
           fi
   lint:

docs/_config.yml

@@ -27,7 +27,7 @@ url: "https://viewcomponent.org"
 remote_theme: pmarsceill/just-the-docs
 search_enabled: true
 color_scheme: custom
-logo: "/logo/viewcomponent-color-logo.svg"
+logo: "/about/logo/viewcomponent-color-logo.svg"
 aux_links:
   "ViewComponent on GitHub":
     - "https://github.com/github/view_component"

docs/CHANGELOG.md → docs/about/CHANGELOG.md

@@ -1,6 +1,7 @@
 ---
 layout: default
 title: Changelog
+parent: About the project
 ---
 
 <!-- Add unreleased changes under the "main" heading. -->
@@ -9,6 +10,10 @@ title: Changelog
 
 ## main
 
+* Reorganize documentation site to include architectural decisions.
+
+    *Joel Hawksley*
+
 ## 2.67.0
 
 * Use ViewComponent::Base.config as the internal endpoint for config.

docs/CODE_OF_CONDUCT.md → docs/about/CODE_OF_CONDUCT.md

@@ -1,6 +1,7 @@
 ---
 layout: default
 title: Code of conduct
+parent: About the project
 ---
 
 # Contributor Covenant Code of Conduct

docs/CONTRIBUTING.md → docs/about/CONTRIBUTING.md

@@ -1,11 +1,12 @@
 ---
 layout: default
 title: Contributing
+parent: About the project
 ---
 
 # Contributing
 
-_ViewComponent is intended to be a safe, welcoming space for collaboration. By participating you agree to abide by the [Contributor Code of Conduct](CODE_OF_CONDUCT.md)._
+_ViewComponent is intended to be a safe, welcoming space for collaboration. By participating you agree to abide by the [Contributor Code of Conduct](about/CODE_OF_CONDUCT.md)._
 
 Hi there! We're thrilled that you'd like to contribute to ViewComponent. Your help is essential for keeping it great.
 
@@ -45,7 +46,7 @@ The codespace environment includes a minimal Rails app with ViewComponent instal
 2. Make sure the tests pass: `bundle exec appraisal rake` (see below for specific cases).
 3. Create a new branch: `git checkout -b my-branch-name`.
 4. Add tests, make the change, and make sure the tests still pass.
-5. Add an entry to the top of `docs/CHANGELOG.md` for the changes, no matter how small.
+5. Add an entry to the top of `docs/about/CHANGELOG.md` for the changes, no matter how small.
 6. If it's your first time contributing, add yourself to `docs/index.md`.
 7. Push to the fork and [submit a pull request](https://github.com/github/view_component/compare).
 8. Wait for the pull request to be reviewed and merged.

docs/compatibility.md → docs/about/compatibility.md

@@ -1,6 +1,7 @@
 ---
 layout: default
 title: Compatibility
+parent: About the project
 ---
 
 # Compatibility

docs/history.md → docs/about/history.md

@@ -1,6 +1,7 @@
 ---
 layout: default
 title: History
+parent: About the project
 ---
 
 # History

docs/about/index.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: About the project
+nav_order: 4
+has_children: true
+---
+
+# About the project

docs/known_issues.md → docs/about/known_issues.md

@@ -1,6 +1,7 @@
 ---
 layout: default
 title: Known issues
+parent: About the project
 ---
 
 # Known issues

docs/logo.md → docs/about/logo.md

@@ -1,6 +1,7 @@
 ---
 layout: default
 title: Logo
+parent: About the project
 ---
 
 # Logo
@@ -13,7 +14,7 @@ title: Logo
 
 Full logo for light backgrounds ([SVG](logo/viewcomponent-color-logo.svg) • [PNG](logo/viewcomponent-color-logo.png))
 
-<img src="/logo/viewcomponent-color-logo-inverse.svg" alt="Full ViewComponent logo in red and white" class="bg-grey-dk-200 p-1 mt-2 mbn-2" style="margin-bottom: -1rem">
+<img src="logo/viewcomponent-color-logo-inverse.svg" alt="Full ViewComponent logo in red and white" class="bg-grey-dk-200 p-1 mt-2 mbn-2" style="margin-bottom: -1rem">
 
 Full logo for dark backgrounds ([SVG](logo/viewcomponent-color-logo-inverse.svg) • [PNG](logo/viewcomponent-color-logo-inverse.png))
 
@@ -33,11 +34,11 @@ Logomark for light backgrounds ([SVG](logo/viewcomponent-black-logomark.svg) •
 
 ### White
 
-<img src="/logo/viewcomponent-white-logo.svg" alt="Full ViewComponent logo in white" class="bg-grey-dk-200 p-1 mt-2 mbn-2" style="margin-bottom: -1rem">
+<img src="logo/viewcomponent-white-logo.svg" alt="Full ViewComponent logo in white" class="bg-grey-dk-200 p-1 mt-2 mbn-2" style="margin-bottom: -1rem">
 
 Full logo for dark backgrounds ([SVG](logo/viewcomponent-white-logo.svg) • [PNG](logo/viewcomponent-white-logo.png))
 
-<img src="/logo/viewcomponent-white-logomark.svg" alt="ViewComponent logomark in white" class="bg-grey-dk-200 p-1 mt-2 mbn-2" style="margin-bottom: -1rem">
+<img src="logo/viewcomponent-white-logomark.svg" alt="ViewComponent logomark in white" class="bg-grey-dk-200 p-1 mt-2 mbn-2" style="margin-bottom: -1rem">
 
 Logomark for dark backgrounds ([SVG](logo/viewcomponent-white-logomark.svg) • [PNG](logo/viewcomponent-white-logomark.png))
 

docs/resources.md → docs/about/resources.md

@@ -1,6 +1,7 @@
 ---
 layout: default
 title: Resources
+parent: About the project
 ---
 
 # Resources

adr/0001-record-architecture-decisions.md → docs/adr/0001-record-architecture-decisions.md

@@ -1,6 +1,12 @@
-# 1. Record architecture decisions
+---
+layout: default
+title: 1. Record architecture decisions
+parent: Architectural decisions
+---
 
-Date: 2021/02/19
+## Date
+
+2021/02/19
 
 ## Status
 

adr/0002-naming-conventions-for-view-components.md → docs/adr/0002-naming-conventions-for-view-components.md

@@ -1,6 +1,12 @@
-# 2. Naming conventions for ViewComponents
+---
+layout: default
+title: 2. Naming conventions for ViewComponents
+parent: Architectural decisions
+---
 
-Date: 2021/07/13
+## Date
+
+2021/07/13
 
 ## Status
 

adr/0003-polymorphic-slot-definitions.md → docs/adr/0003-polymorphic-slot-definitions.md

@@ -1,6 +1,12 @@
-# 3. Polymorphic slots
+---
+layout: default
+title: 3. Polymorphic slots
+parent: Architectural decisions
+---
 
-Date: 2021/09/29
+## Date
+
+2021/09/29
 
 ## Author
 

adr/0004-slots-separate-getter-setter.md → docs/adr/0004-slots-separate-getter-setter.md

@@ -1,6 +1,12 @@
-# Separate Slot Getters and Setters
+---
+layout: default
+title: 4. Separate Slot Getters and Setters
+parent: Architectural decisions
+---
 
-Date: 2022/03/22
+## Date
+
+2022/03/22
 
 ## Author
 

docs/adr/index.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Architectural decisions
+has_children: true
+nav_order: 5
+---
+
+# Architectural decisions

docs/api.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: API
+title: API reference
 nav_order: 3
 ---
 

docs/guide/collections.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Collections
-parent: Guide
+parent: How-to guide
 ---
 
 # Collections

docs/guide/conditional_rendering.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Conditional rendering
-parent: Guide
+parent: How-to guide
 ---
 
 # Conditional rendering

docs/guide/generators.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Generators
-parent: Guide
+parent: How-to guide
 ---
 
 # Generators

docs/guide/getting-started.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Getting started
-parent: Guide
+parent: How-to guide
 nav_order: 1
 ---
 

docs/guide/helpers.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Helpers
-parent: Guide
+parent: How-to guide
 ---
 
 # Helpers

docs/guide/index.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Guide
+title: How-to guide
 nav_order: 2
 has_children: true
 ---

docs/guide/instrumentation.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Instrumentation
-parent: Guide
+parent: How-to guide
 ---
 
 # Instrumentation

docs/guide/javascript_and_css.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Javascript and CSS
-parent: Guide
+parent: How-to guide
 ---
 
 # Javascript and CSS

docs/guide/lifecycle.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Lifecycle
-parent: Guide
+parent: How-to guide
 ---
 
 # Lifecycle

docs/guide/previews.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Previews
-parent: Guide
+parent: How-to guide
 ---
 
 # Previews

docs/guide/slots.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Slots
-parent: Guide
+parent: How-to guide
 ---
 
 # Slots

docs/guide/templates.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Templates
-parent: Guide
+parent: How-to guide
 ---
 
 # Templates

docs/guide/testing.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Testing
-parent: Guide
+parent: How-to guide
 ---
 
 # Testing

docs/guide/translations.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Translations
-parent: Guide
+parent: How-to guide
 ---
 
 # Translations

docs/index.md

@@ -53,7 +53,7 @@ ViewComponent methods are implemented within the scope of the template, encapsul
 
 ### Testing
 
-Unlike traditional Rails templates, ViewComponents can be unit tested. In the GitHub codebase, ViewComponent unit tests are over 100x faster than similar controller tests.
+Unlike traditional Rails templates, ViewComponents can be unit tested easily, thanks to their built-in encapsulation. In the GitHub codebase, ViewComponent unit tests are over 100x faster than similar controller tests.
 
 With ViewComponent, integration tests can be reserved for end-to-end assertions, with permutations covered at the unit level.
 

docs/viewcomponents-in-practice.md → docs/viewcomponents-at-github.md

@@ -1,12 +1,12 @@
 ---
 layout: default
-title: ViewComponents in practice
-nav_order: 4
+title: ViewComponents at GitHub
+nav_order: 6
 ---
 
-# ViewComponents in practice
+# ViewComponents at GitHub
 
-_GitHub's internal guide to building component-driven UI in Rails. Consider it to be more opinion than fact._
+_GitHub's internal guide to building component-driven UI in Rails. More opinion than fact._
 
 ## Why we use ViewComponents