Redocly / Redocly/redoc

I can't determine if powershell code-snippets should be supported

Open
#2,598 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted Type: Enhancement
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

Describe the bug

What languages are supported by syntax highlighter for x-codeSamples (Or is this a question for redoc repo?)

I'm using x-codeSamples and the powershell examples are not highlighted correctly.

To Reproduce
Steps to reproduce the behavior:

Given no redocly.yaml file

and this OpenAPI file

openapi: 3.0.0
info:
  title: "API"
  version: "1.0.0"
  contact:
    name: Contact Name
    email: contact@example.com
    url: https://example.com/
tags:
  - name: Metadata
    description: Metadata related requests
paths:
  /:
    get:
      operationId: getMetadata
      summary: Get metadata from the root of the API
      tags: ["Metadata"]
      x-codeSamples:
        - lang: powershell
          source: |
            # This is a comment "With Quotes" in it
            Invoke-RestMethod -Header @{Hello = 3} -Uri https://example.com/objects -Method Get

        - lang: javascript
          source: |
            // This is a comment "With Quotes" in it
            const response = await axiosClient.get("/objects")
                .withHeader("Hello", 3);
      responses:
        "200":
          description: OK

And running this command

npx @redocly/cli build-docs openapi.yaml

I get a html file that doesn't render the powershell snippet correctly.
I notice it immediately with the first line (the comment) because
it highlights the quoted content as a string and the comment isn't set off
in a comment color

image

Expected behavior

I think (but don't know for sure) that prismjs is the highlighter and it supports powershell.

I expect the syntax highlighting to be rendered appropriately for powershell. (Like if I create a javascript example)

image

Perhaps redoc only supports a limited subset of prismjs languages? I see here that the required lang property is documented but it links to a list of @github/linguist languages.

But the list of linguist languages includes PowerShell.

Perhaps there's a way to configure redoc with additional languages?

Redocly Version(s)

1.25.3

Node.js Version(s)

18.20.4

OS, environment

macOS 14.7

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the provided openapi.yaml example and run npx @redocly/cli build-docs openapi.yaml to inspect how the PowerShell x-codeSamples block is highlighted. Trace the build-docs rendering path and its syntax-highlighting language configuration; done means the PowerShell comment and quoted text render with appropriate syntax highlighting, with the relevant behavior covered by a test if the repository has one.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell, typescript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.