Repository navigation
CQL highlighting #76
Description
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 uses the SQL definition behind the scenes (cql is just an alias for sql in our highlight.js config). 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). So we would need to recruit some CQL experts to help us validate that the language definition properly honors the CQL grammar.
Requirements
- 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 current CI supposedly 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.jsonfile (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.
- Potentially move the repo to the https://github.com/datastax org.
- Submit a PR to add the definition to SUPPORTED_LANGUAGES.md.
- 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.)
Activity
colegoldsmith commentedon Feb 7, 2024
@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 commentedon Feb 7, 2024
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).