search

riptano / docs-ui

The UI and theme for DataStax Docs.
https://riptano.github.io/docs-ui/
Mozilla Public License 2.0
2 stars 0 forks source link

CQL highlighting #76

Open eric-schneider opened 5 months ago

eric-schneider commented 5 months ago

JIRA: DOC-3966

To provide a better user experience for CQL users, we should support CQL language syntax highlighting in code blocks.

Background

The DataStax docs have never had true CQL highlighting. Like the Astra Portal UI, the docs site previously used the SQL definition behind the scenes (the current docs UI doesn't provide any highlighting for CQL). But while the SQL and CQL grammars are similar, they are not the same, and it's important for DataStax as a company to provide the best docs experience for CQL users.

Unfortunately, there is no CQL definition available for highlight.js or any of the common highlighter libraries. Luckily, Therapon Skoteiniotis created an initial beta of a highlight.js language definition for CQL: https://github.com/riptano/highlightjs-cql.

The definition should be considered BETA for now. Not all of the syntax has been tested and some highlighting might appear incorrect (there are a lot of context sensitive keywords in SQL in general and CQL inherits some of it).

Requirements

  1. Complete the repo setup.
    • Should align with best practices of other 3rd party highlightjs definition projects. See Language contributor checklist and SUPPORTED_LANGUAGES.md.
    • The CI works for PRs. The CI will not work for publishing to NPM since we do not have a TOKEN from a valid account in NPM. So that will fail at the moment.
    • The links in the package.json file (to issues and homepages) are a guess since we're not sure which organization the repo will eventually live in yet, or whether it will be made public.
  2. Test the definition against Cassandra 4 CQL grammar and fix any reported issues.
  3. Import the library into the Docs UI.

Stretch goals

  1. Test and update the definition to support the Cassandra 5 CQL grammar. The definition should support the vector type and any other CQL changes in Cassandra 5.
  2. Open-source the definition and publish to NPM under the official DataStax account.
  3. If there's a need, work with the FE team to integrate the highlighter into the Astra Portal UI. (Probably requires porting the definition to Prism.)
colegoldsmith commented 5 months ago

@eric-schneider My vote would be to make that repo public so we don't have to deal with authentication issues in the CI pipelines and when people install it locally. We could quickly get it up and running by publishing to Github packages

That's how we host the Helios packages and a few other JS packages for Astra UI. From experience with the Helios repo being internal it's a pretty negative developer experience trying to install it so I think public is the way to go here, especially since (I assume) there isn't really sensitive code or data in there.

eric-schneider commented 5 months ago

Thanks for the added insight @colegoldsmith. My hope is that we can nurture this project along and get approval to open-source it so we can contribute it back to the greater Cassandra/highlight.js communities. AFAIK we could still maintain it in one of our GitHub orgs, but we would probably want to license it and make it available inline with how other mainstream definitions do it (probably on www.npmjs.com).