Syntax highlighting for polykey cli commands

[shafiqihtsham]

Description

This pr is to allow polykey cli commands in the docs to have appropriate syntax highlighting. Furthermore to improve the syntax highlighting of codeblocks using the sh or bash language prefix.

The current documentation page showing the changes for polykey cli commands is at /docs/tutorials/polykey-cli/managing-vaults. For any sh/bash code blocks they should have better syntax highlighting site wide.

To enable polykey cli syntax highlighting replace code blocks starting with ```sh or ```bash to ```pkcli.

Issues Fixed

• Fixes Implement Syntax Highlighting in Documentation Code Snippets #102

Tasks

• 1. Enable syntax highlighting for polykey cli commands
• 2. Enable syntax highlighting for sh code blocks.

Final checklist

• Domain specific tests
• Full tests
• Updated inline-comment documentation
• Lint fixed
• Squash and rebased
• Sanity check the final build

[CryptoTotalWar]

• https://docusaurus.io/docs/markdown-features/code-blocks
• Additional prism language (shell-session) is not colored. facebook/docusaurus#3559

[CryptoTotalWar]

Separate button we might want to create on the docs for users to switch themes (out of context)

• https://docusaurus.io/docs/2.x/api/themes/configuration

[CryptoTotalWar]

-- chatgpt response analyzing your implementation vs the the desired requirements --

The implementation provided by your colleague involves several custom configurations and enhancements to the Docusaurus and Prism setup. Here's a breakdown of the key aspects and how they relate to your requirement of applying standard themes for specific shells:

Key Aspects of the Current Implementation

1. Prism Theme Configuration:

   • The configuration switches between two themes: GitHub for light mode and Dracula for dark mode. This is set in the docusaurus.config.js file.
   • Custom themes are defined and applied, allowing for specific styling of code blocks based on the language or specific tokens within the language.

2. Custom Language Definitions:

   • A custom language definition for pkcli is created, which is tailored to highlight specific keywords and patterns associated with Polykey CLI commands.
   • This involves defining syntax patterns such as comments, keywords, commands, parameters, and more, which are specific to the Polykey CLI.

3. Integration of Custom Language with Prism:

   • The custom language is integrated into Prism through the prismIncludeLanguages function, which dynamically adds the custom language definition to the Prism instance.
   • This setup ensures that the pkcli language is recognized and highlighted according to the custom rules defined.

Aligning with Your Requirements

While the current implementation focuses on enhancing the highlighting for Polykey CLI commands (pkcli), your primary requirement is to apply universally recognized themes based on the shell used (e.g., bash, zsh). Here's how you can align the current setup with your requirements:

1. Standard Shell Highlighting:

   • Ensure that standard shells like bash and zsh are included in the additionalLanguages configuration in docusaurus.config.js. This makes sure that Prism has the necessary syntax definitions to highlight these shells correctly.
   • You can use the default Prism themes or customize them to more closely match the typical output of these shells. The themes can be adjusted by modifying the custom-prism-theme.ts file or by selecting different themes available from prism-react-renderer.

2. Theme Customization:

   • If the current themes (GitHub and Dracula) do not meet the expectations for shell-specific highlighting, consider exploring other themes or customizing the existing ones to better represent the typical syntax highlighting seen in terminals.
   • Customization can involve adjusting the color schemes for different types of syntax tokens (keywords, strings, commands, etc.) to match those commonly used in terminal environments.

3. Documentation and Usage:

   • Update the documentation to clearly indicate how to use standard shells and any custom languages (like pkcli). This helps maintain clarity and ease of use for those writing and maintaining the documentation.
   • Provide examples in the documentation showing the syntax highlighting for both standard shells and any custom configurations.

Conclusion

The current implementation provides a robust foundation for syntax highlighting customization in Docusaurus. To align it with your primary requirement, focus on ensuring that standard shells are well-supported and that the themes used are recognizable and familiar to developers. This approach enhances the developer experience by providing clear, consistent, and contextually appropriate syntax highlighting across your documentation.

Citations:
https://www.phind.com/search?cache=zjwsyjvjdvx9t9kx0c8ofkq6

[CryptoTotalWar]

I'm closing this PR because i integrated your changes and code into my other PR. However, I have 1 more thing to add to the issue ticket for this that i will add there.