docs/script

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

---

bookmarklets/add-pr-links.js

---

bookmarklets/open-in-vscode.js

---

bookmarklets/pr-link-source.js

---

bookmarklets/view-in-development.js

---

bookmarklets/view-in-production.js

---

check-for-node

This script is run automatically when you run the server locally. It checks whether Node.js is installed.

---

check-github-github-links.js

Run this script to get all broken docs.github.com links in github/github

---

content-migrations/add-early-access-tocs.js

---

content-migrations/add-ghec-to-schema.js

A one-time use script to add GHEC to the REST schema on github/github.

---

content-migrations/add_mini_toc_frontmatter.js

Run this one time script to add max mini toc to rest reference documentation

---

content-migrations/comment-on-open-prs.js

This script finds all open PRs from active branches that touch content files, and adds a comment with steps to run some commands. The idea is to help writers and other Hubbers update their open branches and mitigate conflicts with the main branch.

---

content-migrations/convert-if-to-ifversion.js

Run this one-time script to convert if <feature name> Liquid tags to ifversion <feature name>.

---

content-migrations/create-csv-of-short-titles.js

---

content-migrations/move-unique-image-assets.js

---

content-migrations/remove-html-comments-from-index-files.js

---

content-migrations/topics-upcase.js

---

content-migrations/update-developer-site-links.js

---

content-migrations/update-headers.js

Run this one time script to update headers for accessibility Changing H3 to H2, H4 to H3, H5 to H4, and H6 to H5

---

content-migrations/update-versioning-in-files.js

---

content-migrations/use-short-versions.js

Run this script to convert long form Liquid conditionals (e.g., {% if currentVersion == "free-pro-team" %}) to the new custom tag (e.g., {% ifversion fpt %}) and also use the short names in versions frontmatter.

---

copy-to-test-repo.sh

---

create-glossary-from-spreadsheet.js

This script turns a Google Sheets CSV spreadsheet into a YAML file.

---

deployment/purge-edge-cache.js

---

dev-toc/generate.js

---

dev-toc/index.js

---

dev-toc/layout.html

---

domwaiter.js

---

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.

NOTE: If you get this error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'website-scraper' ...

it's because you haven't installed all the optional dependencies. To do that, run:

npm install --include=optional

---

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/add-ghec-to-fpt.js

Run this script to add versions frontmatter and Liquid conditionals for GitHub Enterprise Cloud, based on anything currently versioned for the specified release of free-pro-team.

---

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 first copies the dereferenced schema from the previous GHES version for the new one. It then replaces references to the previous version's docs URL (e.g., enterprise-server@3.0) with the new version (e.g., enterprise-server@3.1). Finally, it generates a new decorated file from the new dereferenced file to ensure that the dereferenced and decorated files match.

---

enterprise-server-releases/create-webhook-files.js

This script creates new static webhook payload files for a new version.

---

enterprise-server-releases/release-banner.js

This script creates or removes a release candidate banner for a specified version.

---

find-orphaned-assets.js

Print a list of all the asset files that can't be found mentioned in any of the source files (content & code).

---

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.

---

graphql/build-changelog.js

---

graphql/update-files.js

---

graphql/utils/data-filenames.json

---

graphql/utils/process-previews.js

---

graphql/utils/process-schemas.js

---

graphql/utils/process-upcoming-changes.js

---

graphql/utils/schema-helpers.js

---

helpers/action-injections.js

---

helpers/add-redirect-to-frontmatter.js

---

helpers/get-liquid-conditionals.js

---

helpers/get-version-blocks.js

---

helpers/git-utils.js

---

helpers/github.js

---

helpers/remove-deprecated-frontmatter.js

---

helpers/remove-liquid-statements.js

---

helpers/retry-on-error-test.js

Return a function that you can use to run any code within and if it throws you get a chance to say whether to sleep + retry. Example:

async function mainFunction() { if (Math.random() > 0.9) throw new Error('too large') return 'OK' }

const errorTest = (err) => err instanceof Error && err.message.includes('too large') const config = { // all optional attempts: 3, sleepTime: 800, onError: (err, attempts) => console.warn(Failed ${attempts} attempts) } const ok = await retry(errorTest, mainFunction, config)

---

helpers/walk-files.js

A helper that returns an array of files for a given path and file extension.

---

i18n/fix-translation-errors.js

Run this script to fix known frontmatter errors by copying values from english file Currently only fixing errors in: 'type', 'changelog' Please double check the changes created by this script before committing.

---

i18n/homogenize-frontmatter.js

Run this script to fix known frontmatter errors by copying values from english file Translatable properties are designated in the frontmatter JSON schema

---

i18n/lint-translation-files.js

Use this script as part of the translation merge process to output a list of either parsing or rendering errors in translated files and run script/i18n/reset-translated-file.js on them.

---

i18n/msft-report-reset-files.js

---

i18n/msft-reset-files-with-broken-liquid-tags.js

---

i18n/msft-tokens.js

---

i18n/prune-stale-files.js

---

i18n/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.

Usage: script/i18n/reset-translated-file.js

Examples:

$ script/i18n/reset-translated-file.js translations/es-XL/content/actions/index.md

---

i18n/test-html-pages.js

---

i18n/test-render-translation.js

Run this script to test-render all the translation files that have been changed (when compared to the main branch).

---

kill-server-for-jest.js

---

list-image-sizes.js

This script lists all local image files, sorted by their dimensions.

NOTE: If you get this error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'image-size' ...

it's because you haven't installed all the optional dependencies. To do that, run:

npm install --include=optional

---

move-category-to-product.js

Move the files from a category directory to a top-level product and add redirects.

---

move-content.js

Helps you move (a.k.a. rename) a file or a folder and does what's needed with frontmatter redirect_from.

---

pages-with-liquid-titles.js

This is a temporary script to visualize which pages have liquid (and conditionals) in their title frontmatter

---

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.

---

rendered-content-link-checker.js

This script goes through all content and renders their HTML and from there can analyze for various flaws (e.g. broken links)

---

rest/openapi-check.js

Run this script to check if OpenAPI files can be decorated successfully.

---

rest/test-open-api-schema.js

Run this script to check if OpenAPI operations match versions in content/rest operations

---

rest/update-files.js

Run this script to pull openAPI files from github/github, dereference them, and decorate them.

---

rest/utils/create-rest-examples.js

---

rest/utils/decorator.js

---

rest/utils/get-body-params.js

---

rest/utils/get-operations.js

---

rest/utils/operation-schema.js

---

rest/utils/operation.js

---

rest/utils/rest-api-overrides.json

---

rest/utils/webhook-schema.js

---

rest/utils/webhook.js

---

search/analyze-text.js

See how a piece of text gets turned into tokens by the different analyzers. Requires that the index exists in Elasticsearch.

Example:

./script/search/analyze-text.js my words to tokenize

---

search/build-records.js

---

search/find-indexable-pages.js

---

search/index-elasticsearch.js

Creates Elasticsearch index, populates from records, moves the index alias, deletes old indexes.

---

search/lunr-get-index-names.js

---

search/lunr-search-index.js

---

search/parse-page-sections-into-records.js

---

search/popular-pages.js

---

search/search-index-records.js

---

search/search-qa-data.json

---

search/search-qa-test.js

This script is a quality assurance test for the Lunr search configuration. This test runs example queries and expects a specific page to land in the top 3 results.

The data source used by this script is a JSON file script/search/search-qa-data.json, which is populated from spreadsheet data here: https://docs.google.com/spreadsheets/d/1Dt5JRVcmyAGWKBwGjwmXxi7Ww_vdfYLfZ-EFpu2S2CQ/edit?usp=sharing

---

search/sync-search-indices.js

This script is run automatically via GitHub Actions on every push to main to generate searchable data. It can also be run manually. For more info see contributing/search.md

---

search/sync.js

---

search/validate-records.js

---

server-all-languages

Starts the local development server with all of the available languages enabled.

---

server-for-jest.js

---

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

---

start-server-for-jest.js

---

todo

List all the TODOs in our JavaScript files and stylesheets.

---

toggle-ghae-feature-flags.js

Find and replace lightweight feature flags for GitHub AE content.

---

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-internal-links.js

Run this script to find internal links in all content and data Markdown files, check if either the title or link (or both) are outdated, and automatically update them if so.

Exceptions: * Links with fragments (e.g., Bar) will get their root links updated if necessary, but the fragment and title will be unchanged (e.g., Bar). * Links with hardcoded versions (e.g., Foo) will get their root links updated if necessary, but the hardcoded versions will be preserved (e.g., Foo). * Links with Liquid in the titles will have their root links updated if necessary, but the titles will be preserved.

---

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.

---