You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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).
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.
Test the definition against Cassandra 4 CQL grammar and fix any reported issues.
Import the library into the Docs UI.
Stretch goals
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.
Open-source the definition and publish to NPM under the official DataStax account.
@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.
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).
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
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.Stretch goals
The text was updated successfully, but these errors were encountered: