From 8ba413cabc053cdf7d049814d181ab9a2a09a5b9 Mon Sep 17 00:00:00 2001 From: Grace Park Date: Tue, 27 Jul 2021 09:07:18 -0700 Subject: [PATCH] React Cleanup: Documentation (#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 --- .github/CODEOWNERS | 1 - .github/labeler.yml | 8 +++--- Dockerfile | 1 - README.md | 3 +-- components/README.md | 6 +++++ components/Search.tsx | 2 +- components/Survey.tsx | 2 +- {javascripts => components/lib}/copy-code.ts | 0 .../lib}/display-platform-specific-content.ts | 0 .../lib}/display-tool-specific-content.ts | 0 {javascripts => components/lib}/events.ts | 0 {javascripts => components/lib}/experiment.ts | 0 {javascripts => components/lib}/get-csrf.ts | 0 .../lib}/localization.ts | 0 .../lib}/scroll-anchoring.d.ts | 0 .../lib}/toggle-images.ts | 0 {javascripts => components/lib}/user-agent.ts | 0 .../lib}/wrap-code-terms.ts | 0 content/README.md | 10 +++---- contributing/development.md | 3 +-- contributing/search.md | 2 +- data/README.md | 2 +- data/learning-tracks/README.md | 2 +- data/product-examples/README.md | 2 +- .../release-notes/enterprise-server/README.md | 4 +-- data/release-notes/github-ae/README.md | 4 +-- includes/README.md | 4 +-- javascripts/README.md | 26 ------------------- javascripts/index.ts | 21 --------------- lib/get-mini-toc-items.js | 2 +- lib/liquid-tags/README.md | 1 - pages/[versionId]/[productId]/index.tsx | 12 ++++----- pages/_app.tsx | 4 +-- stylesheets/README.md | 1 - stylesheets/tables.scss | 2 +- tests/javascripts/user-agent.js | 2 +- 36 files changed, 40 insertions(+), 87 deletions(-) create mode 100644 components/README.md rename {javascripts => components/lib}/copy-code.ts (100%) rename {javascripts => components/lib}/display-platform-specific-content.ts (100%) rename {javascripts => components/lib}/display-tool-specific-content.ts (100%) rename {javascripts => components/lib}/events.ts (100%) rename {javascripts => components/lib}/experiment.ts (100%) rename {javascripts => components/lib}/get-csrf.ts (100%) rename {javascripts => components/lib}/localization.ts (100%) rename {javascripts => components/lib}/scroll-anchoring.d.ts (100%) rename {javascripts => components/lib}/toggle-images.ts (100%) rename {javascripts => components/lib}/user-agent.ts (100%) rename {javascripts => components/lib}/wrap-code-terms.ts (100%) delete mode 100644 javascripts/README.md delete mode 100644 javascripts/index.ts diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0acc05d843b9..db05b0a3d5d9 100644 --- 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 index 7ca711de3ce7..a885e4a3ab76 100644 --- 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 index 817ab582a270..b320d4c8ae4b 100644 --- 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 index e075c2b23df3..82b70e602b6f 100644 --- 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 new file mode 100644 index 000000000000..084c6b3f5384 --- /dev/null +++ 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 index 973ed138bb64..83667a1ee354 100644 --- 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 index d5423b5c4dad..bbc2e8f3e821 100644 --- 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 b/components/lib/copy-code.ts similarity index 100% rename from javascripts/copy-code.ts rename to components/lib/copy-code.ts diff --git a/javascripts/display-platform-specific-content.ts b/components/lib/display-platform-specific-content.ts similarity index 100% rename from javascripts/display-platform-specific-content.ts rename to components/lib/display-platform-specific-content.ts diff --git a/javascripts/display-tool-specific-content.ts b/components/lib/display-tool-specific-content.ts similarity index 100% rename from javascripts/display-tool-specific-content.ts rename to components/lib/display-tool-specific-content.ts diff --git a/javascripts/events.ts b/components/lib/events.ts similarity index 100% rename from javascripts/events.ts rename to components/lib/events.ts diff --git a/javascripts/experiment.ts b/components/lib/experiment.ts similarity index 100% rename from javascripts/experiment.ts rename to components/lib/experiment.ts diff --git a/javascripts/get-csrf.ts b/components/lib/get-csrf.ts similarity index 100% rename from javascripts/get-csrf.ts rename to components/lib/get-csrf.ts diff --git a/javascripts/localization.ts b/components/lib/localization.ts similarity index 100% rename from javascripts/localization.ts rename to components/lib/localization.ts diff --git a/javascripts/scroll-anchoring.d.ts b/components/lib/scroll-anchoring.d.ts similarity index 100% rename from javascripts/scroll-anchoring.d.ts rename to components/lib/scroll-anchoring.d.ts diff --git a/javascripts/toggle-images.ts b/components/lib/toggle-images.ts similarity index 100% rename from javascripts/toggle-images.ts rename to components/lib/toggle-images.ts diff --git a/javascripts/user-agent.ts b/components/lib/user-agent.ts similarity index 100% rename from javascripts/user-agent.ts rename to components/lib/user-agent.ts diff --git a/javascripts/wrap-code-terms.ts b/components/lib/wrap-code-terms.ts similarity index 100% rename from javascripts/wrap-code-terms.ts rename to components/lib/wrap-code-terms.ts diff --git a/content/README.md b/content/README.md index d6604a3fcf47..b4450606c708 100644 --- 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 index 2e2c4da1fca5..59b7a6408949 100644 --- 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 index aad358bdf0b3..8309c3942124 100644 --- 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 index 7c817fc8a8f0..7e5c15127292 100644 --- 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 index bdbe9e3dfd15..06a1d1294d78 100644 --- 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 index a0a9fc232e4a..fd824bc7a2b1 100644 --- 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 index 5a488316c8e6..61c636ede3bb 100644 --- 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 index b20276bebd62..08c40272e5c3 100644 --- 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 index 756cd58565eb..48276c379231 100644 --- 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 deleted file mode 100644 index a698d5082810..000000000000 --- a/javascripts/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Javascripts - -The code in this directory is destined to run in a web browser! - -The [index.ts](index.ts) file in this directory is bundled by [Webpack](https://github.com/webpack/webpack). In development, we use [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) to bundle automatically while running the server. In production, we run `webpack --mode production` via `npm run build`. - -This file is then referenced in the footer: - -```html - -``` - -Every other file in this directory is written as a module to -be required in `index.ts`. They all have this format: - -```js -module.exports = () => { - // Do some cool browser stuff - // Note: by the time this runs, the DOM will be ready. :) -} -``` - -In development, the bundle will recompile every time a file used by `javascripts/index.ts` is changed. This -ensures that you're always getting an up-to-date version of the script. - -In production, the bundle is compiled during build-time. diff --git a/javascripts/index.ts b/javascripts/index.ts deleted file mode 100644 index 4d1ca18b838e..000000000000 --- a/javascripts/index.ts +++ /dev/null @@ -1,21 +0,0 @@ -// Import our SCSS files so webpack will process them -import '../stylesheets/index.scss' -import displayPlatformSpecificContent from './display-platform-specific-content' -import displayToolSpecificContent from './display-tool-specific-content' -import wrapCodeTerms from './wrap-code-terms' -import localization from './localization' -import experiment from './experiment' -import copyCode from './copy-code' -import initializeEvents from './events' -import toggleImages from './toggle-images' - -document.addEventListener('DOMContentLoaded', async () => { - displayPlatformSpecificContent() - displayToolSpecificContent() - wrapCodeTerms() - localization() - copyCode() - initializeEvents() - experiment() - toggleImages() -}) diff --git a/lib/get-mini-toc-items.js b/lib/get-mini-toc-items.js index 09f93bc1f28b..e45652f1dd01 100644 --- 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 index 161850c3815a..927be5a15134 100644 --- 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 index fa9b35a69667..b474c583e95c 100644 --- 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 index b097625fe3d5..7ec1fdf22dca 100644 --- 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 index 798f2e031846..d456a6ca2d11 100644 --- 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 index 1d74a5458bcf..85641fd74029 100644 --- 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 index f9cd1e81af60..49bc60b84a1f 100644 --- 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', () => {