# Base Queries

Of course! Here are the answers to your questions about using Redocly.

### 1. How do I protect a page with the "pearl" role?

You can control access to specific pages in your documentation portal using role-based access control (RBAC) defined in your `redocly.yaml` configuration file. You need to define the roles and then map them to the files you want to protect.

Here's an example of how you can configure your `redocly.yaml` to only allow users with the "pearl" role to access the `debrief.md` page:


```yaml
# redocly.yaml

# 1. Define your access control roles
access:
  roles:
    pearl: # The name of your role
      # You would typically manage role assignment through your identity provider (IdP)
      # This example assumes the role is passed in a JWT claim.
      claim:
        name: 'user_roles' # The name of the claim in the JWT
        value: 'pearl-squad' # The value that grants the "pearl" role

# 2. Define rules for your page
pages:
  - file: docs/debrief.md
    # 3. Apply the role to the page
    access:
      # Only users with the 'pearl' role can view this page.
      # Users without this role will see a 404 Not Found error.
      - pearl
```

In this configuration:

* `access.roles` defines the available roles. Here, we've created a role named `pearl`.
* The `claim` object specifies how to verify the role from a JSON Web Token (JWT). In this case, it checks for a claim named `user_roles` with the value `pearl-squad`.
* Under `pages`, you specify the file (`docs/debrief.md`) and then apply the `pearl` role to it under the `access` key.


### 2. How do I create a code walkthrough?

Redocly supports a "code walkthrough" format which is great for explaining code step-by-step. This is achieved by using a special syntax within your Markdown files. You can interleave explanations with code blocks, and Redocly will render them in a side-by-side or stacked view.

To create a code walkthrough, you use `---` separators between your Markdown content and the corresponding code blocks.

Here is an example of what the Markdown might look like for a simple Python script:


```markdown
# Code Walkthrough: Hello World

Here we will walk through a simple "Hello World" in Python.


First, we import the `sys` module, which allows us to interact with the system.

```python
import sys
```


Next, we define a simple function called `main` that takes no arguments.


```python
def main():
```


Inside our `main` function, we print the classic "Hello, World!" string to the standard output. We also include the Python version for fun.


```python
    print("Hello, World!")
    print(f"This is Python version {sys.version}")
```


Finally, this standard Python construct checks if the script is being run directly (not imported) and calls the `main` function if it is.


```python
if __name__ == "__main__":
    main()
```


```

When rendered, Redocly will display the descriptive text next to the corresponding code block, making it easy for users to follow along.

### 3. How do I only show the mock server in the Try it console?

You can control which servers are displayed in the "Try it" console by using the `x-redocly-hide-server-vars` extension in your OpenAPI definition. To show *only* the mock server, you can define both your real server and your mock server in the `servers` array, and then use this extension to hide the real one.

Here is an example snippet from an `openapi.yaml` file:

```yaml
# openapi.yaml

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0

# Define your servers
servers:
  # The mock server you want to show
  - url: https://api.redocly.com/mocks/my-api
    description: Mock Server

  # The production server you want to hide from the "Try it" console
  - url: https://api.production.com/v1
    description: Production Server
    x-redocly-hide-server-vars: true # This extension hides the server

paths:
  /users:
    get:
      summary: Get all users
      # ... rest of your path item object
```

By setting `x-redocly-hide-server-vars: true` on the production server entry, it will not be selectable in the "Try it" console, effectively leaving only the "Mock Server" as the available option.

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

Redocly's API monitoring is typically run as a command within a CI/CD pipeline, which can be configured to execute on a schedule. The primary command for this is `redocly test`.

Here’s a general process and an example using GitHub Actions to run tests every day at midnight:

**Step 1: Configure your tests**

First, define your API tests in a file like `redocly.yaml` or a separate file. These tests can check for things like breaking changes, style guide adherence, and more.


```yaml
# redocly.yaml

apis:
  main:
    root: openapi/openapi.yaml

# Define assertion rules
assert:
  # This rule checks for breaking changes against the production version of the API
  - subject: api
    ruleId: no-breaking-changes
    against: 'prod' # 'prod' is an alias for the production version

# This command will run the assertions
test:
  apis:
  - main
```

**Step 2: Schedule the test run in your CI/CD**

You can use a scheduler like `cron` or the built-in scheduling features of your CI/CD provider.

Here is an example of a GitHub Actions workflow that runs every day:


```yaml
# .github/workflows/scheduled-monitoring.yml

name: Scheduled API Monitoring

on:
  schedule:
    # Runs at 00:00 UTC every day
    - cron: '0 0 * * *'

jobs:
  api-monitoring:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Run Redocly API Tests
        run: redocly test
```

This workflow will automatically trigger at the specified `cron` schedule, check out your code, and run the `redocly test` command.

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

You can customize the appearance of your Redocly documentation, including heading colors, through the `theme` object in your `redocly.yaml` configuration file.

To change the color of all heading levels (`h1` through `h6`) to purple, you can add a `theme.headings.color` property.

Here is an example `redocly.yaml` configuration:


```yaml
# redocly.yaml

# ... other configurations

theme:
  # You can customize colors, fonts, and more here
  colors:
    primary:
      main: ‘#9d34da’ # Example: A nice shade of purple for primary actions
  
  # Specifically target headings
  headings:
    # You can set font-family, font-weight, etc.
    # To change the color:
    color: ‘#6A0DAD’ # A standard purple hex code

# ... other configurations
```

In this example:

* `theme.colors.primary.main` changes the primary theme color, which affects links, buttons, and other interactive elements.
* `theme.headings.color` specifically targets all heading elements and sets their text color to the specified purple hex code (`#6A0DAD`). You can use any valid CSS color value.