Skip to content
Last updated

# Direct Docs Queries

Here are the answers to your questions based on the Redocly documentation:

1. How do I protect this debrief.md page so that it requires someone with the "pearl" role to access it?

To restrict access to a specific page to a certain role, you can use the x-access-groups front-matter property in your Markdown file. In your debrief.md file, you would add the following at the top:


x-access-groups:
  - pearl


# Debrief

This content is restricted to users with the "pearl" role.

This configuration ensures that only users who are logged in and have the "pearl" role assigned to them can view the contents of the debrief.md page.

2. How do I create a code walkthrough?

Redocly supports creating code walkthroughs by using a special code-walkthrough layout in your Markdown pages. This layout allows you to present code samples alongside explanations in a clear, step-by-step format.

Here’s a basic example of how to structure your Markdown file for a code walkthrough:


layout: code-walkthrough


# Code Walkthrough Title

Here is the first step of our walkthrough.

```code
// Your code for the first step
console.log("Hello, Step 1!");

Now, for the second step, we do this.

// Your code for the second step
console.log("Hello, Step 2!");

This will render a component that displays your explanations and code snippets in a two-column layout, making it easy for users to follow along.

### 3. How do I only show the mock server in the try it console (not a real server)?

You can control which servers are displayed in the "Try it" console by using the `x-hide-server` extension in your OpenAPI definition. To hide a specific server, add `x-hide-server: true` to its definition.

To show *only* the mock server, you would typically add this extension to all your real server definitions. Redocly automatically discovers and adds the mock server if it's enabled.

Here is an example snippet from an OpenAPI `servers` section:

```yaml
servers:
  - url: https://api.real-server.com/v1
    description: Production server
    x-hide-server: true # This will hide the production server from the "Try it" console
  - url: https://api.staging.com/v1
    description: Staging server
    x-hide-server: true # This will hide the staging server

With this configuration, only the automatically provided mock server will be available for selection in the "Try it" console.

4. How do I run API monitoring using Redocly on a regular schedule?

To run Redocly's API monitoring on a regular schedule, you should integrate the Redocly CLI into a CI/CD pipeline (like GitHub Actions, GitLab CI, or Jenkins) and use the scheduling features of that platform.

Here's an example using a GitHub Actions workflow to run monitoring checks every hour:

  1. Create a workflow file in your repository at .github/workflows/redocly-monitoring.yml.
  2. Add the following configuration to the file:
name: Redocly API Monitoring

on:
  schedule:
    - cron: ‘0 * * * *’ # This runs the job at the beginning of every hour

jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Redocly CLI
        uses: redocly/cli-action@v1
        with:
          redocly-api-key: ${{ secrets.REDOCLY_API_KEY }}

      - name: Run Redocly assertions
        run: redocly assert --project=main

This workflow will trigger automatically on the specified schedule, run your API assertions using the Redocly CLI, and push the results to your Redocly organization.

5. How do I make headings purple colored in Redocly?

You can customize the appearance of your documentation, including heading colors, by using the theme configuration options in your redocly.yaml file. Specifically, you can modify the theme.colors.headings property.

Here is an example of how to set the heading color to purple in your redocly.yaml:

theme:
  colors:
    primary:
      main: ‘#9d38f5’ # Example primary color
    headings:
      main: ‘#6c2ca5’ # A shade of purple for headings
  typography:
    headings:
      fontFamily: ‘Roboto, sans-serif’
      fontWeight: ‘700’

In this example, theme.colors.headings.main is set to a purple hex code. You can adjust the hex code to match the exact shade of purple you want. After applying this configuration, all headings in your documentation will render in the specified color.