b98c83e924
* testing out a rest operations sidebar * cleanup * renamed 5 files * renamed 5 files * set redirect_from on 5 files * renamed 1 files * renamed 1 files * renamed 3 files * renamed 1 files * renamed 1 files * renamed 3 files * renamed 1 files * renamed 2 files * renamed 1 files * renamed 4 files * renamed 15 files * renamed 2 files * renamed 6 files * renamed 1 files * renamed 4 files * renamed 7 files * renamed 1 files * renamed 3 files * renamed 3 files * renamed 1 files * renamed 5 files * renamed 1 files * renamed 1 files * renamed 3 files * renamed 4 files * renamed 1 files * renamed 1 files * renamed 2 files * renamed 4 files * renamed 1 files * renamed 1 files * renamed 1 files * renamed 6 files * renamed 6 files * renamed 4 files * move files * adding more * updating to add restcontext and start of removing data/reusables/rest-reference * removed data/reusables * add a RestMiniTocItem and updating the filtering to add a subcategory so all manually added H3s are in mini tocs in addition to operations * remove console log * [WIP]: REST New Proposal Sidebar (#26471) * saving * update sidebar * remove console log * update guides and overview * import Category for category level rest pages * update undefined restOperations * update restOperationData category and subcategory levels" * minor updates * update get mini toc items function * updating REST context for sidebar * updating rest data * remove console logs * WIP: mini-toc-ing the sidebar Co-authored-by: Robert Sese <rsese@github.com> * A little cleanup * Fix first subcategory link and add some comments * updating anchor links in sidebar * adding updates * remove standalone * update product and maptopic pages using article context * add conditional link wrapper * fix sidebar toggle and versions for enterprise admin * update versions per subcategory * Highlight sidebar link for current page * Update miniToc hash links and hash change tracking * fix unique key in CollapsibleSection * Fix list markup * remove title * update permissions * Hide minitocs on landing (#26594) * hide minitocs on landing page * simplify page components and remove minitoc from sidebar for guides/overview * fix carats and category fix * remove id Co-authored-by: Grace Park <gracepark@github.com> * updating content based on versions script check with the OpenAPI * update script and content files * update script and content/rest files * update to add TocLanding * update script * update index files * add codespaces repository-secrets * remove openapi schema check script * remove minitocs at the top * add h2 about the {title} api * fix tests/unit/openapi-schema.js * Fix linting tests * fix search/topics test * fix tests/unit/pages test * update rest/reference links in components * run prettier * Update components/rest/RestReferencePage.tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update components/rest/RestReferencePage.tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update pages/[versionId]/rest/[category]/[subcategory].tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update pages/[versionId]/rest/[category]/[subcategory].tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update pages/[versionId]/rest/[category]/[subcategory].tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update pages/[versionId]/rest/[category]/[subcategory].tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * Update tests/unit/openapi-schema.js Co-authored-by: Rachael Sewell <rachmari@github.com> * updating comment location * remove dependabot override * remove path-utils current product update for rest * run linter * remove dependabot.md and remove h2 heading on restreference * update the correct product to rest for rest pages * adding comments for updates to path-utils * remove console log * REST sidebar: handle legacy v3 redirects (#26686) * Add script to handle legacy v3 REST redirects * Run the script * Handle a redirect to a redirect * Update REST test URLs * 'await' and test runs subcategory of checks * Update REST URLs for routing/developer-site-redirects tests * Update developer-redirects fixture with new REST URLs * Resolve merge conflicts * Update rest-redirects fixture with new REST URLs * Fix broken links with REST pages re-org * redirectTo could be undefined * Fix script for posterity, can't redirect paths with hashes * Remove invalid hash redirects * Typically don't need to save one-off scripts * Undo redirect changes (not necessary for handling v3 redirects) * Remove script-added redirects * Update old v3 redirects with new REST URLs * No more GHES search indexing page * 'org' not 'organization' * Update fixture data for new REST URLs * revert any content directory changes Co-authored-by: Grace Park <gracepark@github.com> Co-authored-by: Rachael Sewell <rachmari@github.com> * Adding test rest (#26750) * add test to check openapi schema versions and content rest frontmatter versions * update lib/redirects * fix test and add error messages * adding repository secrets * adding repository-secrets.md * Revert "update lib/redirects" This reverts commit 3aafe28265764d5bc09c0c478c8e0ca099c8fbcf. * remove lib/redirects changes and console logs * Update lib/rest/index.js Co-authored-by: Rachael Sewell <rachmari@github.com> * update unique key * Rest client side redirects (#26754) * adding tags subcategory for the rest content repos category * run prettier * bug fix for anchor scrolls" (#26892) * updating width size for rest reference page * Rest sidebar consolidation (#26862) * refactor sidebar * fix articlecontext provider issue on rest product landing page for all versions * fix a bug, create new component * revert change to create new component and fix bug Co-authored-by: Rachael Sewell <rachmari@github.com> * Set currentAnchor with a hashchange handler (#26923) * Rest sidebar design tweaks (#26807) * Rest sidebar design tweaks * tweak color to subtle * use muted color and margin for line * update to design feedback Co-authored-by: Grace Park <gracepark@github.com> * Remove cheerio from rest-collapsible (#26948) * remove cheerio from rest-collapsible * update type * adding endswith instead * use productId instead * one off edge case for secret-scanning * Reorganize subcategory and category, Update pre -> div, Add RestContext (#26950) * reorganize subcategory and category * add RestContext * update comment * update for endpoints page * add comment * move object to restcontext * remove effectiveDate in restcontext * remove width calculation for rest reference page * fix adding manual writer's minitocs to sidebar * update with feedback * update comment * update isRestReferencePage * remove page component and fix bug * adding back rest/index.tsx Co-authored-by: Rachael Sewell <rachmari@github.com> * update content/rest" * add back design tweak * update to div * update margins on rest api reference * remove page component * adding tests * separate product from rest sidebar (#27065) * separate product from rest sidebar * Use ProductCollapsibleSections for product pages * fix tests Co-authored-by: Robert Sese <rsese@github.com> Co-authored-by: Grace Park <gracepark@github.com> * Rest sidebar translations (#27052) * update translations * remove general test Co-authored-by: Robert Sese <rsese@github.com> Co-authored-by: Rachael Sewell <rachmari@github.com>
Scripts
Scripts to rule them all
This directory follows the Scripts to Rule Them All pattern:
bootstrap
Installs/updates all dependencies necessary for the docs environment. Equivalent of npm install.
server
Starts the local development server. Equivalent of npm start.
To keep things snappy, only English and Japanese are enabled. To run the server with all languages enabled, run script/server-all-languages
test
Runs tests. Equivalent of npm test.
Additional scripts
anonymize-branch.js
Flatten all the commits in the current branch into a single anonymized @Octomerger commit
Usage: script/anonymize-branch.js [base-branch] Example: script/anonymize-branch.js "nothing to see here" If the optional [base-branch] argument is omitted, it will default to main
backfill-missing-localizations.js
This script copies any English files that are missing from the translations directory into the translations directory. We only need to run this if problems occur with Crowdin's automatic sync.
check-english-links.js
This script runs once per day via a scheduled GitHub Action to check all links in English content, not including deprecated Enterprise Server content. It opens an issue if it finds broken links. To exclude a link path, add it to lib/excluded-links.js.
check-for-node
This script is run automatically when you run the server locally. It checks whether Node.js is installed.
content-migrations/extended-markdown-tags.js
content-migrations/octicon-tag.js
content-migrations/remove-html-comments-from-index-files.js
content-migrations/site-data-tag.js
content-migrations/update-developer-site-links.js
create-glossary-from-spreadsheet.js
This script turns a Google Sheets CSV spreadsheet into a YAML file.
early-access/clone-for-build.js
This script is run as a postbuild script during staging and deployments on Heroku. It clones a branch in the early-access repo that matches the current branch in the docs repo; if one can't be found, it clones the main branch.
early-access/clone-locally
This script is run on a writer's machine to begin developing Early Access content locally.
early-access/create-branch
This script is run on a writer's machine to create an Early Access branch that matches the current docs-internal branch.
early-access/symlink-from-local-repo.js
This script is run on a writer's machine while developing Early Access content locally. You must pass the script the location of your local copy of the github/docs-early-access git repo as the first argument.
early-access/update-data-and-image-paths.js
This script is run on a writer's machine while developing Early Access content locally. It updates the data and image paths to either include early-access or remove it.
enterprise-server-deprecations/archive-version.js
Run this script during the Enterprise deprecation process to download static copies of all pages for the oldest supported Enterprise version. See the Enterprise deprecation issue template for instructions.
enterprise-server-deprecations/remove-static-files.js
This script removes the static GraphQL, REST, and webhook files for any deprecated GHES versions.
enterprise-server-deprecations/remove-version-markup.js
Run this script after an Enterprise deprecation to remove Liquid statements and frontmatter that contain the deprecated Enterprise version. See the Enterprise deprecation issue template for instructions.
enterprise-server-releases/create-graphql-files.js
This script creates the static GraphQL files for a new version.
enterprise-server-releases/create-rest-files.js
This script creates new static openAPI files for a new version and modifies the info.version.
enterprise-server-releases/create-webhook-files.js
This script creates new static webhook payload files for a new version.
enterprise-server-releases/ghes-to-ghae-versioning.js
Run this script to add versions frontmatter and Liquid conditionals for GitHub AE, based on anything currently versioned for the provided release of Enterprise Server. This script should be run as part of the Enterprise Server release process.
enterprise-server-releases/release-banner.js
This script creates or removes a release candidate banner for a specified version.
get-new-dotcom-path.js
Pass this script any old dotcom path (e.g., articles/foo or foo.md) and it will output the new path in the content/github directory.
get-new-version-path.js
Helper script that returns a "new" versioned path given an "old" versioned path.
Examples:
Given: /github/getting-started-with-github/using-github Returns: /free-pro-team@latest/github/getting-started-with-github/using-github
Given: /enterprise/admin/installation/upgrading-github-enterprise Returns: /enterprise-server@2.22/admin/installation/upgrading-github-enterprise
graphql/build-changelog.js
graphql/update-files.js
graphql/utils/data-filenames.json
graphql/utils/prerender-objects.js
graphql/utils/process-previews.js
graphql/utils/process-schemas.js
graphql/utils/process-upcoming-changes.js
graphql/utils/schema-helpers.js
list-image-sizes.js
This script lists all local image files, sorted by their dimensions.
move-category-to-product.js
Pass this script three arguments: 1. current category path (e.g., github/automating-your-workflows-with-github-actions) 2. new product ID (e.g., actions) 3. new product name in quotes (e.g., "GitHub Actions") and it does everything that needs to be done to make the category into a new product.
move-reusables-to-markdown.js
This script moves reusables out of YAML files into individual Markdown files.
pages-with-liquid-titles.js
This is a temporary script to visualize which pages have liquid (and conditionals) in their title frontmatter
ping-staging-apps.js
This script finds all Heroku staging apps and pings them to make sure they're always "warmed" and responsive to requests.
prevent-pushes-to-main.js
This script is intended to be used as a git "prepush" hook. If the current branch is main, it will exit unsuccessfully and prevent the push.
prevent-translation-commits.js
This script is run as a git precommit hook (installed by husky after npm install). It detects changes to files the in the translations folder and prevents the commit if any changes exist.
purge-fastly
Run this script to manually purge the Fastly cache. Note this script requires a FASTLY_SERVICE_ID and FASTLY_TOKEN in your .env file.
purge-fastly-by-url.js
Run this script to manually purge the Fastly cache for all language variants of a single URL or for a batch of URLs in a file. This script does not require authentication.
reconcile-category-dirs-with-ids.js
An automated test checks for discrepancies between category directory names and slugified category titles as IDs.
If the test fails, a human needs to run this script to update the directory names and add appropriate redirects.
This script is not currently supported on Windows.
reconcile-filenames-with-ids.js
An automated test checks for discrepancies between filenames and autogenerated heading IDs. If the test fails, a human needs to run this script to update the filenames.
This script is not currently supported on Windows.
remove-stale-staging-apps.js
This script removes all stale Heroku staging apps that outlasted the closure of their corresponding pull requests, or correspond to spammy pull requests.
remove-unused-assets.js
Run this script to remove reusables and image files that exist in the repo but are not used in content files. It also displays a list of unused variables. Set the --dry-run to flag to print results without deleting any files. For images you don't want to delete, add them to ignoreList in lib/find-unused-assets.js
reset-translated-file.js
This is a convenience script for replacing the contents of translated files with the English content from their corresponding source file.
It's intended to be a workaround to temporarily bypass Crowdin parser bugs while we wait for translators to fix them.
Usage: script/i18n/reset-translated-file.js
Examples:
reset a single translated file using a relative path: $ script/i18n/reset-translated-file.js translations/es-XL/content/actions/index.md
reset a single translated file using a full path: $ script/i18n/reset-translated-file.js /Users/z/git/github/docs-internal/translations/es-XL/content/actions/index.md
reset all language variants of a single English file (using a relative path): script/i18n/reset-translated-file.js content/actions/index.md script/i18n/reset-translated-file.js data/ui.yml
reset all language variants of a single English file (using a full path): script/i18n/reset-translated-file.js /Users/z/git/github/docs-internal/content/desktop/index.md script/i18n/reset-translated-file.js /Users/z/git/github/docs-internal/data/ui.yml
rest/update-files.js
Run this script to pull openAPI files from github/github, dereference them, and decorate them.
rest/utils/create-code-samples.js
rest/utils/get-operations.js
rest/utils/operation-schema.js
rest/utils/operation.js
sample-unix-commands.md
server-all-languages
Starts the local development server with all of the available languages enabled.
standardize-frontmatter-order.js
Run this script to standardize frontmatter fields in all content files, per the order: - title - intro - product callout - productVersion - map topic status - hidden status - layout - redirect
sync-search-indices.js
This script is run on a schedule every four hours to generate searchable data. It can also be run manually. To run it manually, click "Run workflow" button in the Actions tab. For more info see contributing/search.md
todo
List all the TODOs in our JavaScript files and stylesheets.
update-enterprise-dates.js
This script fetches data from https://github.com/github/enterprise-releases/blob/master/releases.json and updates lib/enterprise-dates.json, which the site uses for various functionality.
update-readme.js
This script crawls the script directory, hooks on special comment markers in each script, and adds the comment to script/README.md.