Skip to main content

Getting Started

Prerequisites​

Before you begin, install the following programs:

  • Visual Studio Code (VS Code) or your preferred Individual Development Environment (IDE)
  • Node.js (version 14.0.0 or later)
  • Git and/or GitHub Desktop

These instructions are for U.S. Government (USG) computers and assume VS Code as the IDE.

✅ Installing VS Code​

Visual Studio Code is a lightweight code editor used to write, edit, and manage software and documentation projects. It is the recommended IDE for working on the RMC Software Documentation site.

VS Code is available for request through the USACE App Portal. It does not require approval, and installation should occur automatically. If installation doesn’t begin in the next 48 hours, contact the Enterprise Service Desk at (866) 562-2348.

Several users have reported issues with VS Code installing correctly onto their USG computers from the App Portal and have required assistance from CIO-G6.

Recommended Extension

For improved visual clarity and syntax highlighting when editing .mdx files in VS Code, install the MDX extension from the Visual Studio Code Marketplace.

✅ Installing Node.js​

Node.js is a JavaScript runtime that uses an asynchronous, event-driven architecture to support the development of scalable web applications. The Docusaurus framework used to build the RMC Software Documentation website relies on tools that run on Node.js.

While Node.js is available through the USACE App Portal, it is recommended to download it directly from the official Node.js website.

To install Node.js:

  1. On a non-USG computer, download the Standalone Binary (.zip) installation file from the Node.js Downloads page. It is recommended to download the LTS (Long-Term Support) version of the software.
Download Node.js

  1. On your USG computer, create a folder on the C: drive named Portable Software (or something similar). Place the Node.js zip file in that folder and extract the contents.

  2. Add Node.js to your PATH:

  • Open the Windows menu and type environment variables into the Search Bar

  • Click on Edit environment variables for your account

    • DO NOT click on Edit the system environment variables — that requires admin rights
Edit environment variables
  • In the Environment Variables window, select "Path" and click Edit...
Edit user PATH
  • Click New and paste the file path for your Node.js folder (e.g., C:\Portable Software\nodejs). This should be the folder that holds the node.exe file.
  • Click OK to close the environment variable windows
Add Node.js to PATH

  1. Confirm installation of Node.js and Node Package Manager (npm):

    • Open Command Prompt and type node --version
      • If installed correctly, the terminal will return the Node.js version number (e.g., v22.17.0).
    • Then type npm --version
      • npm is bundled with Node.js and does not require a separate installation. It should return a version number (e.g., 11.4.2).
    • NOTE: The Node.js and npm version numbers will not be the same.
Check installation of Node.js and npm
  1. If either version command fails, ensure that the path to your Node.js folder is correctly entered in the Environment Variables. Repeat steps 3–4 if necessary.

✅ Installing Git and GitHub Desktop​

Git is a version control system that tracks changes to files over time. It allows you to commit updates, create branches, and synchronize code with shared repositories. GitHub Desktop provides a graphical interface for Git, making it easier to use for contributors who prefer not to work from the command line.

These tools are required to:

  • Download (clone) the RMC Software Documentation repository from GitHub
  • Make updates locally on your machine
  • Push changes back to GitHub for review and publication

Git and GitHub Desktop are both available for installation from the USACE App Portal.

To install Git and GitHub Desktop:

1. Request installation from the App Portal

  • Open the USACE App Portal
  • Search for and request the following applications:
    • Git
    • GitHub Desktop
  • Installation should occur automatically. If installation doesn’t begin in the next 48 hours, contact the Enterprise Service Desk at (866) 562-2348.
USACE App Portal Git and GitHub Desktop

2. Verify installation

  • Open Command Prompt and type git --version
    • If installed correctly, the terminal will return the Git version number (e.g., git version 2.42.0.windows.2).
GitHub Desktop application confirmation
  • To confirm GitHub Desktop is installed, open the Windows Start Menu and search for GitHub Desktop. The application should appear in the list.
GitHub Desktop application icon
info

GitHub Desktop can be used to clone, commit, push, and pull changes to and from the repository without using Git commands directly. However, Git is still required under the hood, even when using GitHub Desktop.

Cloning the Project​

To begin working on the RMC Software Documentation website, you’ll first need to clone the project repository to your local machine and install the required dependencies.

✅ Clone the Repository

  1. Open GitHub Desktop
  2. Go to File → Clone Repository
  3. In the Search Bar of the Clone a repository window, enter RMC-Software-Documentation and select the repository under the USACE-RMC GitHub account.
  4. Choose a Local path to save the repository.
  5. Click Clone.
GitHub Desktop application icon

✅ Open the Project Directory

  1. In GitHub Desktop, go to the Current Repository dropdown and select RMC-Software-Documentation
  2. Click Repository → Open in Visual Studio Code (or your configured IDE)

✅ Install Dependencies

Once the project is open in your IDE, open a terminal and run:

npm install

This will install all necessary dependencies to edit, test, build, and deploy the Docusaurus project. This includes folders such as .docusaurus/ and node_modules that are not tracked in GitHub.

warning

Node.js MUST be installed before running npm install or other Node.js-based commands. If not installed, an error will be returned.

Run, Build, and Deploy the Site​

💻 Running Locally​

To preview the RMC Software Documentation site on your local machine during development, run:

npm run start

This will start the development server at http://localhost:3000. Any changes you make to the source files will automatically reload the site in your browser.

🏗️ Building for Production​

To generate the optomized static files for deployment, run:

npm run build

This creates a build/ directory containing the static HTML, CSS, and JavaScript files. These are suitable for deployment to the GitHub Pages hosting service.

🚀 Deployment​

Important

Deployment should be coordinated with a site administrator. Unauthorized deployment may overwrite live documentation.

To deploy the site to GitHub Pages, follow these steps:

  1. Set the GitHub user environment variable:

    $env:GIT_USER="USACE-RMC"

  2. Deploy the site:

    npm run deploy

This command builds the site and pushes the contents of the build/ directory to the gh-pages branch of the repository using the specified GIT_USER.

Last updated on