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

---

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-deps.js

This script checks which modules you have used in your code and then makes sure they are listed as dependencies in your package.json, or vice-versa

https://github.com/dependency-check-team/dependency-check

The ignore array is for client-side or build-time stuff that doesn't get require()d in the normal way.

---

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.

---

check-s3-images.js

Run this script in your branch to check whether any images referenced in content are not in an expected S3 bucket. You will need to authenticate to S3 via awssume to use this script. Instructions for the one-time setup are here.

---

content-migrations/extended-markdown-tags.js

---

content-migrations/octicon-tag.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.

---

delete-unused-staging-apps.js

This script finds and lists all the Heroku staging apps and deletes any leftover apps that have closed PRs

---

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/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/remove-hidden-schema-members.rb

---

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 unsuccesfully 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-extraneous-translation-files.js

An automated test checks for files in the translations/ directory that do not have an equivalent English file in the content/ directory, and fails if it finds extraneous files. When the test fails, a human needs to run this script to remove the files.

---

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/reset-translated-file.js

Examples:

reset a single translated file using a relative path: $ script/reset-translated-file.js translations/es-XL/content/actions/index.md

reset a single translated file using a full path: $ script/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/reset-translated-file.js content/actions/index.md script/reset-translated-file.js data/ui.yml

reset all language variants of a single English file (using a full path): script/reset-translated-file.js /Users/z/git/github/docs-internal/content/desktop/index.md script/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 decided in https://github.com/github/docs-internal/issues/9658#issuecomment-485536265.

---

sync-algolia-search-indices.js

This script is run automatically via GitHub Actions on every push to master to generate searchable data and upload it to our Algolia account. It can also be run manually. For more info see contributing/search.md

---

todo

List all the TODOs in our JavaScript files and stylesheets.

---

update-enterprise-dates.js

Run this script during Enterprise releases and deprecations. It uses the GitHub API to get dates from enterprise-releases and updates lib/enterprise-dates.json. The help site uses this JSON to display dates at the top of some Enterprise versions.

This script requires that you have a GitHub Personal Access Token in a .env file. If you don't have a token, get one here. If you don't have an .env file in your docs checkout, run this command in Terminal:

cp .env.example .env

Open the .env file in a text editor, and find the GITHUB_TOKEN= placeholder. Add your token after the equals sign.

Do not commit the .env file; just leave it in your checkout.

---

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.

---

update-s3cmd-config.js

This script is used by other scripts to update temporary AWS credentials and authenticate to S3. See docs at Setting up awssume and S3cmd.

---

update-versioning-in-files.js

---

upload-images-to-s3.js

Use this script to upload individual or batched asset files to a versioned S3 bucket. Run upload-images-to-s3.js --help for usage details.

---