React Cleanup: Documentation (github#20517)

* initial documentation changes * editing layouts terminology * update to match other files * move javascripts to components/lib * fix: dockerfile * update based on Mikes updates to the javascripts directory * update components/README.md Co-authored-by: Mike Surowiec <[email protected]>
JonnyZockt · Jul 27, 2021 · 8ba413c · 8ba413c
1 parent 61ed797
commit 8ba413c
Show file tree

Hide file tree

Showing 36 changed files with 40 additions and 87 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -10,7 +10,6 @@
 /.github/ @github/docs-engineering
 /script/ @github/docs-engineering
 /includes/ @github/docs-engineering
-/layouts/ @github/docs-engineering
 app.json @github/docs-engineering
 Dockerfile @github/docs-engineering
 package-lock.json @github/docs-engineering

diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -1,8 +1,6 @@
 engineering:
   - lib/*
   - lib/**/*
-  - layouts/*
-  - layouts/**/*
   - middleware/*
   - middleware/**/*
   - tests/*
@@ -11,5 +9,7 @@ engineering:
   - stylesheets/**/*
   - script/*
   - script/**/*
-  - javascripts/*
-  - javascripts/**/*
+  - components/*
+  - components/**/*
+  - pages/*
+  - pages/**/*
diff --git a/Dockerfile b/Dockerfile
@@ -37,7 +37,6 @@ FROM all_deps as builder
 
 ENV NODE_ENV production
 
-COPY javascripts ./javascripts
 COPY stylesheets ./stylesheets
 COPY pages ./pages
 COPY components ./components

diff --git a/README.md b/README.md
@@ -58,8 +58,7 @@ In addition to the README you're reading right now, this repo includes other REA
 - [data/variables/README.md](data/variables/README.md)
 - [includes/liquid-tags/README.md](includes/liquid-tags/README.md)
 - [includes/README.md](includes/README.md)
-- [javascripts/README.md](javascripts/README.md)
-- [layouts/README.md](layouts/README.md)
+- [components/README.md](components/README.md)
 - [lib/liquid-tags/README.md](lib/liquid-tags/README.md)
 - [middleware/README.md](middleware/README.md)
 - [script/README.md](script/README.md)

diff --git a/components/README.md b/components/README.md
@@ -0,0 +1,6 @@
+# Components
+
+⚠️ This area is a work-in-progress.
+
+This is the main source for our React components. They can be rendered by the server or the client via [Next.js](https://nextjs.org). The starting point for any component usage is the `pages/` directory, which uses a file-system routing paradigm to match paths to pages that then render these components.
+
diff --git a/components/Search.tsx b/components/Search.tsx
@@ -2,7 +2,7 @@ import { useState, useEffect, useRef, ReactNode } from 'react'
 import { useRouter } from 'next/router'
 import debounce from 'lodash/debounce'
 import { useTranslation } from 'components/hooks/useTranslation'
-import { sendEvent, EventType } from '../javascripts/events'
+import { sendEvent, EventType } from 'components/lib/events'
 import { useMainContext } from './context/MainContext'
 import { useVersion } from 'components/hooks/useVersion'
 import cx from 'classnames'

diff --git a/components/Survey.tsx b/components/Survey.tsx
@@ -2,7 +2,7 @@ import { useState, useRef } from 'react'
 import { ThumbsdownIcon, ThumbsupIcon } from '@primer/octicons-react'
 import { useTranslation } from 'components/hooks/useTranslation'
 import { Link } from 'components/Link'
-import { sendEvent, EventType } from '../javascripts/events'
+import { sendEvent, EventType } from 'components/lib/events'
 
 enum ViewState {
   START = 'START',

diff --git a/javascripts/copy-code.ts → components/lib/copy-code.ts b/javascripts/copy-code.ts → components/lib/copy-code.ts
diff --git a/...ipts/display-platform-specific-content.ts → .../lib/display-platform-specific-content.ts b/...ipts/display-platform-specific-content.ts → .../lib/display-platform-specific-content.ts
diff --git a/javascripts/display-tool-specific-content.ts → ...ents/lib/display-tool-specific-content.ts b/javascripts/display-tool-specific-content.ts → ...ents/lib/display-tool-specific-content.ts
diff --git a/javascripts/events.ts → components/lib/events.ts b/javascripts/events.ts → components/lib/events.ts
diff --git a/javascripts/experiment.ts → components/lib/experiment.ts b/javascripts/experiment.ts → components/lib/experiment.ts
diff --git a/javascripts/get-csrf.ts → components/lib/get-csrf.ts b/javascripts/get-csrf.ts → components/lib/get-csrf.ts
diff --git a/javascripts/localization.ts → components/lib/localization.ts b/javascripts/localization.ts → components/lib/localization.ts
diff --git a/javascripts/scroll-anchoring.d.ts → components/lib/scroll-anchoring.d.ts b/javascripts/scroll-anchoring.d.ts → components/lib/scroll-anchoring.d.ts
diff --git a/javascripts/toggle-images.ts → components/lib/toggle-images.ts b/javascripts/toggle-images.ts → components/lib/toggle-images.ts
diff --git a/javascripts/user-agent.ts → components/lib/user-agent.ts b/javascripts/user-agent.ts → components/lib/user-agent.ts
diff --git a/javascripts/wrap-code-terms.ts → components/lib/wrap-code-terms.ts b/javascripts/wrap-code-terms.ts → components/lib/wrap-code-terms.ts
diff --git a/content/README.md b/content/README.md
@@ -139,10 +139,10 @@ shortTitle: Contributing to projects
 
 ### `layout`
 
-- Purpose: Wrap the page in a custom HTML layout.
-- Type: `String` that matches the name of the layout file, without an extension.
-For a layout named `layouts/article.html`, the value would be `article`.
-- Optional. If omitted, `layouts/default.html` is used.
+- Purpose: Render the proper page layout.
+- Type: `String` that matches the name of the layout.
+For a layout named `components/landing`, the value would be `product-landing`.
+- Optional. If omitted, `DefaultLayout` is used.
 
 ### `children`
 
@@ -192,7 +192,7 @@ featuredLinks:
 
 ### `changelog`
 
-- Purpose: Render a list of items pulled from [GitHub Changelog](https://github.blog/changelog/) on product landing pages (ex: `layouts/product-landing.html`). The one exception is Education, which pulls from https://github.blog/category/community/education.
+- Purpose: Render a list of items pulled from [GitHub Changelog](https://github.blog/changelog/) on product landing pages (ex: `components/landing`). The one exception is Education, which pulls from https://github.blog/category/community/education.
 - Type: `Object`, properties:
   - `label` -- must be present and corresponds to the labels used in the [GitHub Changelog](https://github.blog/changelog/)
   - `prefix` -- optional string that starts each changelog title that should be omitted in the docs feed. For example, with the prefix `GitHub Actions: ` specified, changelog titles like `GitHub Actions: Some Title Here` will render as `Some Title Here` in the docs feed).

diff --git a/contributing/development.md b/contributing/development.md
@@ -75,8 +75,7 @@ For more info about working with this site, check out these READMEs:
 - [data/variables/README.md](../data/variables/README.md)
 - [includes/liquid-tags/README.md](../includes/liquid-tags/README.md)
 - [includes/README.md](../includes/README.md)
-- [javascripts/README.md](../javascripts/README.md)
-- [layouts/README.md](../layouts/README.md)
+- [components/README.md](../components/README.md)
 - [lib/liquid-tags/README.md](../lib/liquid-tags/README.md)
 - [middleware/README.md](../middleware/README.md)
 - [script/README.md](../script/README.md)

diff --git a/contributing/search.md b/contributing/search.md
@@ -101,7 +101,7 @@ Why do we need this? For our daily shipping needs, it's tolerable that search up
 
 ### Code files
 
-- [javascripts/search.js](javascripts/search.js) - The browser-side code that enables search.
+- [components/lib/search.ts](components/lib/search.ts) - The browser-side code that enables search.
 - [lib/search/algolia-client.js](lib/search/algolia-client.js) - A thin wrapper around the [algoliasearch](https://ghub.io/algoliasearch) Node.js module for interacting with the Algolia API.
 - [lib/search/algolia-search-index.js](lib/search/algolia-search-index.js) - A class for generating structured search data from repository content and syncing it with the remote Algolia service. This class has built-in validation to ensure that all records are valid before they're uploaded. This class also takes care of removing deprecated records, and compares existing remote records with the latest local records to avoid uploading records that haven't changed.
 - [script/sync-search-indices.js](script/sync-search-indices.js) - The script used by the Actions workflow to update search indices on our Algolia account. This can also be [run in the development environment](#development).

diff --git a/data/README.md b/data/README.md
@@ -26,7 +26,7 @@ Webhook payload JSON files are used in the [`webhook events docs`](../content/de
 
 ## ui.yml
 
-`ui.yml` contains localized strings used in HTML layouts.
+`ui.yml` contains localized strings used in layouts.
 
 ## Learning Tracks
 

diff --git a/data/learning-tracks/README.md b/data/learning-tracks/README.md
@@ -29,7 +29,7 @@ Learning track data for a product is defined in two places:
 
 ## Versioning
 
-Versioning for learning tracks is processed at page render time. The code lives in [`lib/learning-tracks.js`](lib/learning-tracks.js), which is called by `page.render()`. The processed learning tracks are then rendered by `layouts/product-sublanding.html`.
+Versioning for learning tracks is processed at page render time. The code lives in [`lib/learning-tracks.js`](lib/learning-tracks.js), which is called by `page.render()`. The processed learning tracks are then rendered by `components/sublanding`.
 
 Liquid conditionals do **not** have to be used for versioning in the YAML file for guides. Only the learning track guides that apply to the current version will be rendered automatically. If there aren't any tracks with guides that belong to the current version, the learning tracks section will not render at all.
 

diff --git a/data/product-examples/README.md b/data/product-examples/README.md
@@ -38,7 +38,7 @@ where the syntax for `versions` is the same as the [frontmatter `versions` prope
 
 The product example data is added to the `context` object in `middleware/contextualizers/product-examples.js`.
 
-The data is then rendered by `layouts/product-landing.html`.
+The data is then rendered by `components/landing`.
 
 ## Schema enforcement
 

diff --git a/data/release-notes/enterprise-server/README.md b/data/release-notes/enterprise-server/README.md
@@ -26,9 +26,9 @@ The YAML data is processed and sorted by `middleware/contextualizers/release-not
 
 ### Layouts
 
-The `context` object data is rendered by `layouts/release-notes.html` and `includes/enterprise-server-release-notes.html`.
+The `context` object data is rendered by `components/release-notes`.
 
-The release notes page has a custom design with CSS in `stylesheets/release-notes.scss` and client-side JavaScript in `javascripts/release-notes.js`.
+The release notes page has a custom design with CSS in `stylesheets/release-notes.scss`.
 
 ### Schema
 

diff --git a/data/release-notes/github-ae/README.md b/data/release-notes/github-ae/README.md
@@ -24,9 +24,9 @@ The YAML data is processed and sorted by `middleware/contextualizers/release-not
 
 ### Layouts
 
-The `context` object data is rendered by `layouts/release-notes.html` and `includes/github-ae-release-notes.html`.
+The `context` object data is rendered by `components/release-notes`.
 
-The release notes page has a custom design with CSS in `stylesheets/release-notes.scss` and client-side JavaScript in `javascripts/release-notes.js`.
+The release notes page has a custom design with CSS in `stylesheets/release-notes.scss`.
 
 ### Schema
 

diff --git a/includes/README.md b/includes/README.md
@@ -6,11 +6,11 @@ called "partials".
 
 ## Using Includes
 
-This example injects the contents of `includes/header.html` into the 
+This example injects the contents of `includes/graphql-enum.html` into the 
 page:
 
 ```
-{% include header %}
+{% include graphql-enum %}
 ```
 
 ## Writing Includes

diff --git a/javascripts/README.md b/javascripts/README.md
diff --git a/javascripts/index.ts b/javascripts/index.ts
diff --git a/lib/get-mini-toc-items.js b/lib/get-mini-toc-items.js
@@ -11,7 +11,7 @@ export default function getMiniTocItems(html, maxHeadingLevel = 2, headingScope
   const headings = $(selector)
 
   // return an array of objects containing each heading's contents, level, and optional platform.
-  // layouts/article.html uses these as follows:
+  // Article layout uses these as follows:
   //  - `contents` to render the mini TOC headings
   //  - `headingLevel` the `2` in `h2`; used for determining required indentation
   //  - `platform` to show or hide platform-specific headings via client JS

diff --git a/lib/liquid-tags/README.md b/lib/liquid-tags/README.md
@@ -14,7 +14,6 @@ This directory contains custom Liquid tags for outputting dynamic content. These
 Tags can be used in:
 
 - Articles and TOCs (`content/**/*.md`)
-- Layout files (`layouts/*.html`)
 - Include files (`includes/*.html`)
 
 Tags always expect a single argument, a language agnostic href:

diff --git a/pages/[versionId]/[productId]/index.tsx b/pages/[versionId]/[productId]/index.tsx
@@ -2,12 +2,12 @@ import { GetServerSideProps } from 'next'
 
 // "legacy" javascript needed to maintain existing functionality
 // typically operating on elements **within** an article.
-import copyCode from 'javascripts/copy-code'
-import displayPlatformSpecificContent from 'javascripts/display-platform-specific-content'
-import displayToolSpecificContent from 'javascripts/display-tool-specific-content'
-import localization from 'javascripts/localization'
-import toggleImages from 'javascripts/toggle-images'
-import wrapCodeTerms from 'javascripts/wrap-code-terms'
+import copyCode from 'components/lib/copy-code'
+import displayPlatformSpecificContent from 'components/lib/display-platform-specific-content'
+import displayToolSpecificContent from 'components/lib/display-tool-specific-content'
+import localization from 'components/lib/localization'
+import toggleImages from 'components/lib/toggle-images'
+import wrapCodeTerms from 'components/lib/wrap-code-terms'
 
 import {
   MainContextT,

diff --git a/pages/_app.tsx b/pages/_app.tsx
@@ -7,8 +7,8 @@ import { defaultThemeProps, getThemeProps } from 'components/lib/getThemeProps'
 
 import '../stylesheets/index.scss'
 
-import events from 'javascripts/events'
-import experiment from 'javascripts/experiment'
+import events from 'components/lib/events'
+import experiment from 'components/lib/experiment'
 
 type MyAppProps = AppProps & { csrfToken: string; themeProps: typeof defaultThemeProps }
 const MyApp = ({ Component, pageProps, csrfToken, themeProps }: MyAppProps) => {

diff --git a/stylesheets/README.md b/stylesheets/README.md
@@ -16,4 +16,3 @@ as much as we can, and avoid writing custom styles whenever possible.
 
 See [styleguide.github.com/primer](https://styleguide.github.com/primer/) for reference.
 
-We use [Webpack](https://github.com/webpack/webpack) to process the files - see [javascripts/README.md](../javascripts/README.md) for more information on how these files are compiled.
diff --git a/stylesheets/tables.scss b/stylesheets/tables.scss
@@ -12,7 +12,7 @@
   width: 100%;
   /* We want to keep table-layout: auto so that column widths dynamically adjust;
   otherwise entries get needlessly squashed into narrow columns. As a workaround,
-  we use javascripts/wrap-code-terms.js to prevent some reference table content
+  we use components/lib/wrap-code-terms.js to prevent some reference table content
   from expanding beyond the horizontal boundaries of the parent element. */
   table-layout: auto;
 

diff --git a/tests/javascripts/user-agent.js b/tests/javascripts/user-agent.js
@@ -1,4 +1,4 @@
-import parseUserAgent from '../../javascripts/user-agent'
+import parseUserAgent from '../../components/lib/user-agent'
 
 describe('parseUserAgent', () => {
   it('android, chrome', () => {
Original file line number	Diff line number	Diff line change
Expand Up		@@ -16,4 +16,3 @@ as much as we can, and avoid writing custom styles whenever possible.

		See [styleguide.github.com/primer](https://styleguide.github.com/primer/) for reference.

		We use [Webpack](https://github.com/webpack/webpack) to process the files - see [javascripts/README.md](../javascripts/README.md) for more information on how these files are compiled.