README.adoc

DataStax Starlight for JMS Docs

This repository contains the source files for the DataStax Starlight for JMS documentation.

Contents

• Get started
• Publish docs

Get started

The documentation is written in AsciiDoc-formatted source files located in the modules directory.

Make a simple update

For simple updates like fixing typos or modifying existing prose, it’s easiest to edit the source files directly on GitHub.

ℹ️	You’ll need Write privileges on the repository to edit files directly on GitHub.

1. Find the file you want to edit in the modules directory.

2. Click the Edit icon in the upper-right corner of the file view.

3. Make your changes in the editor.

4. Click Commit changes…​

5. Enter a description for your commit and click Propose changes.

6. On the Open a pull request screen, enter a title and description for your change, assign reviewers, then click Create pull request.

7. Once the pull request is open, an automatic draft preview build is triggered. Once complete, the build system posts a comment on the pull request with a link to the draft site for you to preview your changes.

Edit docs locally

If you need to make substantial updates to the documentation, you’ll want to clone the repository so you can work with the source files locally.

1. Clone this repository

   git clone https://github.com/datastax/starlight-for-jms-docs.git

2. Create a classic personal access token for your GitHub account. When configuring the token, set the Expiration to at least 90 days and select everything under the Repo scope.

   ❗	Copy your personal access token to a temporary location — you’ll need it later.

3. Authorize your personal access token so that it can access repositories in the Riptano and DataStax organizations in GitHub.

4. Populate the credential store with your personal access token. For most people this means doing the following:

   1. Create the file $HOME/.git-credentials and open it in your editor.

   2. Add the following line:

      https://TOKEN:@github.com

      Replace TOKEN with the personal access token you copied from GitHub.

   3. Save and close the file.

5. If you don’t already have Node.js installed, do the following:

   1. Install nvm.

      If you’re on macOS, you can install nvm using Homebrew:

      brew install nvm

   2. Use nvm to install Node.js.

      nvm install --lts

      nvm use --lts

      nvm alias default node

6. Install the project dependencies.

   cd starlight-for-jms-docs

   npm install

7. Build the site.

   npm run build:local

   If the build was successful, you’ll see the following output in your terminal:

   Site generation complete!
   Open file:///Users/USERNAME/repos/starlight-for-jms-docs/build/site/index.html in a browser to view your site.

   To view the site, paste the entire file:/// path into your browser’s address bar and press Return.

Publish docs

To learn how to publish documentation to docs.datastax.com, see the datastax-docs-site README.