Skip to main content

Create a New Doc

Here's a high-level overview of how to create a new Sumo Logic doc.


  • You must have a GitHub account to contribute to Sumo Logic documentation.
  • We recommend adding 2FA protection when contributing to Sumo Logic repositories.
  • Help us keep Sumo Logic open and inclusive by reviewing our Code of Conduct.

Step 1: Fork the Sumo Docs repository​

To create new doc, we recommend forking our repo, making changes in a new branch, and submitting a PR for review.

Feel free to reach out to the Docs Team to discuss. We're happy to work with you on the project and talk through rewriting content, changing flow, adding a new topic or section, and deprecating content.

  1. Fork the Sumo Docs repository. Remember to sync your fork and update branches as needed.
  2. Review our README documentation guidelines.
  3. Create a new branch from your forked repo using a name that best describes the work or references a GitHub issue number. For example: <your initials>-apps-gitlab.

Step 2: Create a doc file​

The docs site is comprised of GitHub-flavored markdown files containing content like bulleted instructions, screenshots, tables, interactive code samples, and more.

  1. Open your new branch in your IDE and go to the /docs folder.
  2. In the appropriate subfolder (e.g., /docs/metrics), create a markdown file in the format <your-file>.md.

Step 3: Add doc title and metadata​

See Frontmatter to learn how.

Step 4: Write your doc​

In your IDE, write the body of your doc.

  • See our Style Guide to learn how to write and style content, add code snippets, import multimedia, and more. Doc body text content is written in GitHub-flavored markdown, with some customizations.
  • See our recommended authoring tools.
Recommended authoring tools
If you're new to GitHub and/or writing Markdown, we recommend using the following apps (click to expand):
  • VS Code: Development application to open the repo, edit and create files, and preview pages as you write. We recommend the following extensions:
    • Markdown All in One
    • Markdown Preview GitHub Styling
    • Markdown Preview Enhanced
    • Markdown Preview Mermaid Support and Mermaid Markdown Syntax Highlighting for charts and graphs
  • GitHub Desktop: Easy-to-use interface to update your local machine clone, create branches, push to GitHub, and more.
  • iTerm2 - Terminal application for macOS. You can also install Oh My Zsh for theming.

Step 5: Add doc to the navigation menu​

To add your new doc to the left-nav menu, you'll need to add its name and file path to the sidebars.ts file.

Doc Team Support

The Sumo Logic Doc Team can help you add your doc to the sidebar and top navigation. If you have suggestions, include those in your Pull Request description. If you add the documentation to the sidebar, the team will review the location and names for building and placement in navigation.

Step 6: Add doc to the hub page​

Hub pages are /index pages that display all docs in that section in card view. Some cards are sorted by alphabetical order, and some are sorted by importance and/or ranking.

As an example, let's say you needed to add a Best Practices doc to the Send Data hub page.

Once you decide on placement, use the card HTML code in that doc to create a new entry.

Step 7: Create CID URL​

Because docs links appear throughout our product, and canonical links often change, we assign each doc a permalink URL containing a content ID (CID) number. The permalink URL does a 301 redirect to the canonical URL. This way, future changes to the canonical URL (such as a product name change) won't impact the Learn More links for the user. And it will save us code changes to the UI, providing great flexibility when we need to make quick changes.

This URL is then placed in the UI in the appropriate place. For example, links to a metrics page, which appears in the product in the Metrics section as a help link.

To create a CID:

  1. In your GitHub authoring tool (like Atom or VS Code), open our cid-redirects.json file, which contains all 301 redirects.
  2. Scroll down to the CIDs section, where the line items start with "/cid/".
  3. Find an unused CID number, then add that value along with the canonical URL. For example:
    "/cid/5120": "/docs/manage/users-roles/roles/create-manage-roles",
    "/cid/5121": "/docs/example",
    "/cid/5122": "/docs/get-started/library",

Ideally, although not required, this should be placed near URLs similar to the one you're adding.

Step 8: Preview your changes​

Next, you'll build and deploy a local instance of the Sumo Logic Docusaurus site.

Our site is built using Docusaurus, a static site generator, which builds your site as simple static HTML, JavaScript, and CSS files. To view our install installment requirements and preview your build, see Building Locally in our README.

We use Yarn for all installs and builds. Never use NPM commands for installing or updating packages.

Step 9: Submit your request​

  1. Commit your changes to the branch with a meaningful message.
    pull request Use descriptive commit messages (and issue or ticket numbers, if applicable) detailing the content updates you are entering for content. One-line messages are fine for small changes, but bigger changes should look like this:
    $ git commit -m "A brief summary of the commit
    > A paragraph describing what changed and its impact."
  2. Set permissions to allow maintainers to edit and update the PR (learn more).
  3. Push your branch to the forked repo.
  4. Visit our repo after pushing your branch. If you see an option to Compare & pull request for your branch, click this.
    • If you don't see it, create a new PR.
      1. Select main for the base branch. This is the branch all staging and production content builds from.
      2. Select your branch for the compare.
      3. Click Create pull request.
  5. On the Pull Request page, enter the following:
    • Make sure base branch is main and compare branch is the one you pushed.
    • Enter a title for the PR.
    • Include an issue number from GitHub or Jira, etc.
    • Describe what changed, new pages, updates.
    • Apply a label that best describes your contribution.
  6. [Optional]: For urgent, high-priority PRs (for example, doc edits tied to a GA release happening within 24 hours):
    1. Add the GA release date to the title. For example, AWS Integration release (GA: Jan 1, 2023).
    2. From the labels list, select the hot🔥 label, signifying it's an extremely urgent PR.
    3. For internal Sumos only: after completion of all GitHub checks, send your PR link to the #doc-int and #open-source Slack channels for review.
  7. Click Create pull request.
    pull request
  8. First-time contributors will be prompted in a comment to sign our Contributor License Agreement. We allow individual contributions and contributions made on behalf of companies.
    CLA bot

What happens next?​

Docs Team members will review contributions, provide feedback, and approve. When approved, the Docs Team will merge and update staging. Updates to production will be handled by the Docs Team.

Privacy Statement
Terms of Use

Copyright © 2023 by Sumo Logic, Inc.