Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
michaelgwelch opened this issue Sep 26, 2024 · 3 comments
Open

Comments

@michaelgwelch
Copy link

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: [email protected]
    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

@tatomyr
Copy link
Contributor

tatomyr commented Sep 27, 2024

I believe it's a Redoc issue. @AlexVarchuk could you take a look at it?

@AlexVarchuk AlexVarchuk transferred this issue from Redocly/redocly-cli Sep 27, 2024
@AlexVarchuk
Copy link
Collaborator

Hi @michaelgwelch, thank you for the question. Redoc does not highlight powershell syntax.
In your case, using powershell is required? Could you use bash instead of powershell?

PR is welcome

@michaelgwelch
Copy link
Author

michaelgwelch commented Sep 27, 2024

@AlexVarchuk @tatomyr thanks for quick responses. Alex, no, powershell is not required; but it is the tool I use most often (using the Invoke-RestMethod command) for testing our own apis and want to include it in our examples. We have several other examples (curl, c#, javascript) as well so not a big deal. Fortunately, redoc supports a lang of text which I can use for powershell. While it's plain it is better than incorrect highlighting. So this will be useable.

You can consider this question answered. I just wanted to know if I was doing something wrong and I was getting mixed signals trying to figure it out from the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants