diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 48232c6e2..fb54e89ea 100644 --- a/.github/CODEOWNERS +++ b/.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 diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 65484c74d..4b50f19db 100644 --- a/.github/workflows/lint.yml +++ b/.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: diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 120000 index 7a7656e80..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1 +0,0 @@ -docs/CHANGELOG.md \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..adbe85392 Binary files /dev/null and b/CHANGELOG.md differ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 120000 index 3d7a75f92..000000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1 +0,0 @@ -docs/CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..2d8ca8f21 Binary files /dev/null and b/CODE_OF_CONDUCT.md differ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 120000 index 49d1b98f9..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -docs/CONTRIBUTING.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..4832c697b Binary files /dev/null and b/CONTRIBUTING.md differ diff --git a/docs/_config.yml b/docs/_config.yml index 6f88c2ceb..ce807c02a 100644 --- a/docs/_config.yml +++ b/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" diff --git a/docs/CHANGELOG.md b/docs/about/CHANGELOG.md similarity index 99% rename from docs/CHANGELOG.md rename to docs/about/CHANGELOG.md index 2f9814252..c02eb49bb 100644 --- a/docs/CHANGELOG.md +++ b/docs/about/CHANGELOG.md @@ -1,6 +1,7 @@ --- layout: default title: Changelog +parent: About the project --- @@ -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. diff --git a/docs/CODE_OF_CONDUCT.md b/docs/about/CODE_OF_CONDUCT.md similarity index 99% rename from docs/CODE_OF_CONDUCT.md rename to docs/about/CODE_OF_CONDUCT.md index 56236706b..b2100cae5 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/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 diff --git a/docs/CONTRIBUTING.md b/docs/about/CONTRIBUTING.md similarity index 97% rename from docs/CONTRIBUTING.md rename to docs/about/CONTRIBUTING.md index 4cf9e67f8..b99ee6a34 100644 --- a/docs/CONTRIBUTING.md +++ b/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. diff --git a/docs/compatibility.md b/docs/about/compatibility.md similarity index 98% rename from docs/compatibility.md rename to docs/about/compatibility.md index a715d3456..07ebd417a 100644 --- a/docs/compatibility.md +++ b/docs/about/compatibility.md @@ -1,6 +1,7 @@ --- layout: default title: Compatibility +parent: About the project --- # Compatibility diff --git a/docs/history.md b/docs/about/history.md similarity index 97% rename from docs/history.md rename to docs/about/history.md index dc1c20cbb..52e37ba9c 100644 --- a/docs/history.md +++ b/docs/about/history.md @@ -1,6 +1,7 @@ --- layout: default title: History +parent: About the project --- # History diff --git a/docs/about/index.md b/docs/about/index.md new file mode 100644 index 000000000..9b930bbba --- /dev/null +++ b/docs/about/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: About the project +nav_order: 4 +has_children: true +--- + +# About the project diff --git a/docs/known_issues.md b/docs/about/known_issues.md similarity index 97% rename from docs/known_issues.md rename to docs/about/known_issues.md index 67e4d7e15..f4be633d0 100644 --- a/docs/known_issues.md +++ b/docs/about/known_issues.md @@ -1,6 +1,7 @@ --- layout: default title: Known issues +parent: About the project --- # Known issues diff --git a/docs/logo.md b/docs/about/logo.md similarity index 80% rename from docs/logo.md rename to docs/about/logo.md index 3f90aa559..49686987a 100644 --- a/docs/logo.md +++ b/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)) -Full ViewComponent logo in red and white +Full ViewComponent logo in red and white 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 -Full ViewComponent logo in white +Full ViewComponent logo in white Full logo for dark backgrounds ([SVG](logo/viewcomponent-white-logo.svg) • [PNG](logo/viewcomponent-white-logo.png)) -ViewComponent logomark in white +ViewComponent logomark in white Logomark for dark backgrounds ([SVG](logo/viewcomponent-white-logomark.svg) • [PNG](logo/viewcomponent-white-logomark.png)) diff --git a/docs/logo/readme-dark.svg b/docs/about/logo/readme-dark.svg similarity index 100% rename from docs/logo/readme-dark.svg rename to docs/about/logo/readme-dark.svg diff --git a/docs/logo/readme-light.svg b/docs/about/logo/readme-light.svg similarity index 100% rename from docs/logo/readme-light.svg rename to docs/about/logo/readme-light.svg diff --git a/docs/logo/viewcomponent-black-logo.png b/docs/about/logo/viewcomponent-black-logo.png similarity index 100% rename from docs/logo/viewcomponent-black-logo.png rename to docs/about/logo/viewcomponent-black-logo.png diff --git a/docs/logo/viewcomponent-black-logo.svg b/docs/about/logo/viewcomponent-black-logo.svg similarity index 100% rename from docs/logo/viewcomponent-black-logo.svg rename to docs/about/logo/viewcomponent-black-logo.svg diff --git a/docs/logo/viewcomponent-black-logomark.png b/docs/about/logo/viewcomponent-black-logomark.png similarity index 100% rename from docs/logo/viewcomponent-black-logomark.png rename to docs/about/logo/viewcomponent-black-logomark.png diff --git a/docs/logo/viewcomponent-black-logomark.svg b/docs/about/logo/viewcomponent-black-logomark.svg similarity index 100% rename from docs/logo/viewcomponent-black-logomark.svg rename to docs/about/logo/viewcomponent-black-logomark.svg diff --git a/docs/logo/viewcomponent-color-logo-inverse.png b/docs/about/logo/viewcomponent-color-logo-inverse.png similarity index 100% rename from docs/logo/viewcomponent-color-logo-inverse.png rename to docs/about/logo/viewcomponent-color-logo-inverse.png diff --git a/docs/logo/viewcomponent-color-logo-inverse.svg b/docs/about/logo/viewcomponent-color-logo-inverse.svg similarity index 100% rename from docs/logo/viewcomponent-color-logo-inverse.svg rename to docs/about/logo/viewcomponent-color-logo-inverse.svg diff --git a/docs/logo/viewcomponent-color-logo.png b/docs/about/logo/viewcomponent-color-logo.png similarity index 100% rename from docs/logo/viewcomponent-color-logo.png rename to docs/about/logo/viewcomponent-color-logo.png diff --git a/docs/logo/viewcomponent-color-logo.svg b/docs/about/logo/viewcomponent-color-logo.svg similarity index 100% rename from docs/logo/viewcomponent-color-logo.svg rename to docs/about/logo/viewcomponent-color-logo.svg diff --git a/docs/logo/viewcomponent-color-logomark.png b/docs/about/logo/viewcomponent-color-logomark.png similarity index 100% rename from docs/logo/viewcomponent-color-logomark.png rename to docs/about/logo/viewcomponent-color-logomark.png diff --git a/docs/logo/viewcomponent-color-logomark.svg b/docs/about/logo/viewcomponent-color-logomark.svg similarity index 100% rename from docs/logo/viewcomponent-color-logomark.svg rename to docs/about/logo/viewcomponent-color-logomark.svg diff --git a/docs/logo/viewcomponent-white-logo.png b/docs/about/logo/viewcomponent-white-logo.png similarity index 100% rename from docs/logo/viewcomponent-white-logo.png rename to docs/about/logo/viewcomponent-white-logo.png diff --git a/docs/logo/viewcomponent-white-logo.svg b/docs/about/logo/viewcomponent-white-logo.svg similarity index 100% rename from docs/logo/viewcomponent-white-logo.svg rename to docs/about/logo/viewcomponent-white-logo.svg diff --git a/docs/logo/viewcomponent-white-logomark.png b/docs/about/logo/viewcomponent-white-logomark.png similarity index 100% rename from docs/logo/viewcomponent-white-logomark.png rename to docs/about/logo/viewcomponent-white-logomark.png diff --git a/docs/logo/viewcomponent-white-logomark.svg b/docs/about/logo/viewcomponent-white-logomark.svg similarity index 100% rename from docs/logo/viewcomponent-white-logomark.svg rename to docs/about/logo/viewcomponent-white-logomark.svg diff --git a/docs/resources.md b/docs/about/resources.md similarity index 99% rename from docs/resources.md rename to docs/about/resources.md index 93c0e782e..62d12a687 100644 --- a/docs/resources.md +++ b/docs/about/resources.md @@ -1,6 +1,7 @@ --- layout: default title: Resources +parent: About the project --- # Resources diff --git a/adr/0001-record-architecture-decisions.md b/docs/adr/0001-record-architecture-decisions.md similarity index 78% rename from adr/0001-record-architecture-decisions.md rename to docs/adr/0001-record-architecture-decisions.md index 1c8632201..211642a03 100644 --- a/adr/0001-record-architecture-decisions.md +++ b/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 diff --git a/adr/0002-naming-conventions-for-view-components.md b/docs/adr/0002-naming-conventions-for-view-components.md similarity index 93% rename from adr/0002-naming-conventions-for-view-components.md rename to docs/adr/0002-naming-conventions-for-view-components.md index 6e30f41a7..4ea78533a 100644 --- a/adr/0002-naming-conventions-for-view-components.md +++ b/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 diff --git a/adr/0003-polymorphic-slot-definitions.md b/docs/adr/0003-polymorphic-slot-definitions.md similarity index 98% rename from adr/0003-polymorphic-slot-definitions.md rename to docs/adr/0003-polymorphic-slot-definitions.md index fbf9f52db..0bfe51579 100644 --- a/adr/0003-polymorphic-slot-definitions.md +++ b/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 diff --git a/adr/0004-slots-separate-getter-setter.md b/docs/adr/0004-slots-separate-getter-setter.md similarity index 95% rename from adr/0004-slots-separate-getter-setter.md rename to docs/adr/0004-slots-separate-getter-setter.md index e5439253f..8cc2ad276 100644 --- a/adr/0004-slots-separate-getter-setter.md +++ b/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 diff --git a/docs/adr/index.md b/docs/adr/index.md new file mode 100644 index 000000000..4ed20cb23 --- /dev/null +++ b/docs/adr/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: Architectural decisions +has_children: true +nav_order: 5 +--- + +# Architectural decisions diff --git a/docs/api.md b/docs/api.md index ffadcf677..7da45baaa 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,6 +1,6 @@ --- layout: default -title: API +title: API reference nav_order: 3 --- diff --git a/docs/guide/collections.md b/docs/guide/collections.md index 7ecdd7762..ac490346e 100644 --- a/docs/guide/collections.md +++ b/docs/guide/collections.md @@ -1,7 +1,7 @@ --- layout: default title: Collections -parent: Guide +parent: How-to guide --- # Collections diff --git a/docs/guide/conditional_rendering.md b/docs/guide/conditional_rendering.md index 6b4fef975..cb65e3630 100644 --- a/docs/guide/conditional_rendering.md +++ b/docs/guide/conditional_rendering.md @@ -1,7 +1,7 @@ --- layout: default title: Conditional rendering -parent: Guide +parent: How-to guide --- # Conditional rendering diff --git a/docs/guide/generators.md b/docs/guide/generators.md index 02974410a..a71f758a2 100644 --- a/docs/guide/generators.md +++ b/docs/guide/generators.md @@ -1,7 +1,7 @@ --- layout: default title: Generators -parent: Guide +parent: How-to guide --- # Generators diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 9c8fb7bd3..2c947ec94 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,7 +1,7 @@ --- layout: default title: Getting started -parent: Guide +parent: How-to guide nav_order: 1 --- diff --git a/docs/guide/helpers.md b/docs/guide/helpers.md index 72d4282e8..38413b998 100644 --- a/docs/guide/helpers.md +++ b/docs/guide/helpers.md @@ -1,7 +1,7 @@ --- layout: default title: Helpers -parent: Guide +parent: How-to guide --- # Helpers diff --git a/docs/guide/index.md b/docs/guide/index.md index fc1ffcc4d..8d6227a28 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -1,6 +1,6 @@ --- layout: default -title: Guide +title: How-to guide nav_order: 2 has_children: true --- diff --git a/docs/guide/instrumentation.md b/docs/guide/instrumentation.md index 3af12d51d..712164adf 100644 --- a/docs/guide/instrumentation.md +++ b/docs/guide/instrumentation.md @@ -1,7 +1,7 @@ --- layout: default title: Instrumentation -parent: Guide +parent: How-to guide --- # Instrumentation diff --git a/docs/guide/javascript_and_css.md b/docs/guide/javascript_and_css.md index 98e3874ad..0a7dda2ec 100644 --- a/docs/guide/javascript_and_css.md +++ b/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 diff --git a/docs/guide/lifecycle.md b/docs/guide/lifecycle.md index 5cf40599d..de159c4c3 100644 --- a/docs/guide/lifecycle.md +++ b/docs/guide/lifecycle.md @@ -1,7 +1,7 @@ --- layout: default title: Lifecycle -parent: Guide +parent: How-to guide --- # Lifecycle diff --git a/docs/guide/previews.md b/docs/guide/previews.md index 2304c2ffa..ee9b3169a 100644 --- a/docs/guide/previews.md +++ b/docs/guide/previews.md @@ -1,7 +1,7 @@ --- layout: default title: Previews -parent: Guide +parent: How-to guide --- # Previews diff --git a/docs/guide/slots.md b/docs/guide/slots.md index 645f3e6cd..0e2dbaf1e 100644 --- a/docs/guide/slots.md +++ b/docs/guide/slots.md @@ -1,7 +1,7 @@ --- layout: default title: Slots -parent: Guide +parent: How-to guide --- # Slots diff --git a/docs/guide/templates.md b/docs/guide/templates.md index 5b890a675..106c2a5be 100644 --- a/docs/guide/templates.md +++ b/docs/guide/templates.md @@ -1,7 +1,7 @@ --- layout: default title: Templates -parent: Guide +parent: How-to guide --- # Templates diff --git a/docs/guide/testing.md b/docs/guide/testing.md index acb19a0ba..f8754265a 100644 --- a/docs/guide/testing.md +++ b/docs/guide/testing.md @@ -1,7 +1,7 @@ --- layout: default title: Testing -parent: Guide +parent: How-to guide --- # Testing diff --git a/docs/guide/translations.md b/docs/guide/translations.md index 334614091..43675ca98 100644 --- a/docs/guide/translations.md +++ b/docs/guide/translations.md @@ -1,7 +1,7 @@ --- layout: default title: Translations -parent: Guide +parent: How-to guide --- # Translations diff --git a/docs/index.md b/docs/index.md index 243320655..dd886cda5 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/viewcomponents-in-practice.md b/docs/viewcomponents-at-github.md similarity index 98% rename from docs/viewcomponents-in-practice.md rename to docs/viewcomponents-at-github.md index 4fe38ce23..008c6c41b 100644 --- a/docs/viewcomponents-in-practice.md +++ b/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 diff --git a/script/release b/script/release index 9bbff7410..2e2041143 100755 --- a/script/release +++ b/script/release @@ -36,7 +36,7 @@ update_readme() { \\ \\ ## $1.$2.$3 - }" docs/CHANGELOG.md + }" docs/about/CHANGELOG.md } update_ruby_version() { @@ -66,7 +66,7 @@ build_docs() { add_changed_files() { git add \ docs/api.md \ - docs/CHANGELOG.md \ + docs/about/CHANGELOG.md \ docs/_data/library.yml \ Gemfile.lock \ lib/view_component/version.rb @@ -82,7 +82,7 @@ push() { echo "####################################################" echo "Now, open a PR with this branch and merge it to main" echo "Then, run script/publish on main to release the gem" - echo "Finally, create a GitHub release https://github.com/github/view_component/releases/new with the changes from docs/CHANGELOG" + echo "Finally, create a GitHub release https://github.com/github/view_component/releases/new with the changes from docs/about/CHANGELOG" echo "####################################################" } diff --git a/view_component.gemspec b/view_component.gemspec index efc9d0246..a98381fa0 100644 --- a/view_component.gemspec +++ b/view_component.gemspec @@ -23,7 +23,7 @@ Gem::Specification.new do |spec| "public gem pushes." end - spec.files = Dir["LICENSE.txt", "README.md", "app/**/*", "docs/CHANGELOG.md", "lib/**/*"] + spec.files = Dir["LICENSE.txt", "README.md", "app/**/*", "docs/about/CHANGELOG.md", "lib/**/*"] spec.require_paths = ["lib"] spec.required_ruby_version = ">= 2.4.0"