This repo contains the documentation source files for the DataStax Docs Contributor’s Guide documentation.

The docs are written in AsciiDoc and use Antora to generate the HTML output.

• Contributing to the docs
• Working with Docs Contributor’s Guide docs
  • Submitting your changes
• Generating and viewing the HTML output locally
• Repo dependencies
  • Dependencies in package.json

Although this repo is maintained by the DataStax Docs team, contributions from the community are gratefully accepted, and encouraged.

Why should you contribute to the Docs Contributor’s Guide docs?

• It makes the Docs team’s job easier.

• It makes your job easier.

• It helps DataStax and Cassandra users more quickly.

How do you contribute?

The majority of DataStax documentation source files are written in AsciiDoc, a lightweight, human-readable markup language. You can contribute to the documentation by adding content to, or editing, the AsciiDoc files in this repo.

For instructions, see Working with Docs Contributor’s Guide docs below.

Before following the steps below, first make sure that you have git installed on your computer.

1. Using a terminal, clone the adoc-howto repository (this repository) onto your computer.

   git clone https://github.com/datastax/adoc-howto.git

2. cd into the cloned repo.

   cd adoc-howto

3. If you have previously cloned the repo, switch to the main branch and do a git pull to get the latest changes.

   git checkout main && git pull

4. Create a working branch.

   git checkout -b <working-branch>

   Replace <working-branch> with a descriptive name or a related JIRA ticket number.

5. Locate the .adoc file that you wish to edit and open it in your preferred editor (.adoc files are stored in the docs-src directory). Make sure to save your changes once you’re done making edits.

   If adding a new page, make sure to add it to the appropriate location in the docs-src directory and then update the appropriate navigation file (nav.adoc) so that the new page will show up in the left-hand navigation of the docs website.

6. Preview your changes by running a local build.

7. Commit your changes.

   git commit -m "<description-of-changes>"

8. Push your changes to GitHub.

   git push -u origin <working-branch>

You can generate the HTML docs locally to view changes and check your work. Note that these steps assume you’ve already cloned the adoc-howto repo and checked out the main branch (see Working with Docs Contributor’s Guide docs for more information).

Using a terminal, cd into the cloned repo directory and run the following command:

If the docs built successfully, you’ll see output similar to the following:

The build-locally.sh script prints the local file path of the generated docs, and prompts you about starting a local web server for viewing the docs.

• Y - Select to view the site build with the advanced functionality of a web server: To view the docs using the local web server.

• N - Select to view only the generated docs HTML: To view the generated HTML files directly.

1. Copy the entire file:/// path from the terminal output, and open it in a web browser.

2. In the file browser, click docs, then click on any of the .html files.

3. From here, you can browse the documentation just like you would on docs.datastax.com.

4. If you end up making further edits to the documentation, simply run the build-locally.sh script again to view your latest changes.

1. When prompted to start the local web server, type Y and press Return.

   When the web server starts up, you’ll see output similar to the following:

      ┌────────────────────────────────────────────────────┐
      │                                                    │
      │   Serving!                                         │
      │                                                    │
      │   - Local:            http://localhost:3000        │
      │   - On Your Network:  http://192.168.86.141:3000   │
      │                                                    │
      │   Copied local address to clipboard!               │
      │                                                    │
      └────────────────────────────────────────────────────┘

2. Copy the Local: address (in this case, http://localhost:3000) and open it in a web browser.

3. From the Index of adoc-howto/ page, click build/ > contributors-guide/ > docs/

4. From here, you can browse the documentation just like you would on docs.datastax.com.

5. Once you’re done viewing the documentation, go back to your terminal window and press Ctrl+C to shut down the web server.

6. If you end up making further edits to the documentation, simply run the build-locally.sh script again to view your latest changes.

The build-locally.sh script should take care of installations required to build the docs. However, if you get a message that you need to install NodeJS, run the following commands (macOS):