Implement Syntax Highlighting in Documentation Code Snippets

[CryptoTotalWar]

Is your feature request related to a problem? Please describe.

Currently, our documentation displays code snippets in a plain, unstyled format. This absence of syntax highlighting detracts from the visual appeal and readability of our content, especially for users who are accustomed to seeing color-coded variables and commands in their development environments, such as Visual Studio editors or terminals.

Describe the solution you'd like

We propose enhancing our documentation by introducing dynamic syntax highlighting for code snippets. This enhancement would adapt the presentation of code to reflect the active shell theme of the reader, thereby improving the visual appeal and readability of our documentation. For example, transforming a snippet from:

Polykey identities -h

to a styled version that might look like:

polykey(blue) identities(grey) -h(grey)

This solution aims to bring our documentation in line with modern standards of technical writing, providing a more engaging and accessible learning experience for our users.

Additional context

Implementing syntax highlighting in our documentation would not only elevate our presentation standards to match leading technical documents but also significantly enhance the user experience by making our content more intuitive and accessible. This feature, while not critical, represents a valuable aesthetic enhancement that could distinguish our documentation in terms of quality and user engagement.

[linear[bot]]

PRO-211 Implement Syntax Highlighting in Documentation Code Snippets

[CryptoTotalWar]

With this issue ticket, in PR #101 we've integrated the changes made in PR #103 and closed the later.

@shafiqihtsham

• added a custom language called pkcli that provides custom syntax highlighting for pk commands in the docs.
• added a custom light theme and dark theme
• enabled supporting of sh, bash, pkcli, powershell, etc.
  • note that zsh would also work
• can add additional supported languages in the docusorous config that are supported by PRISM
• for codeblocks with polykey commands, we want to highlight them using ``'pkcli
• close codeblock
• Users can toggle b/w light mode and dark mode. However, there is an issue with this.

[CryptoTotalWar]

There is 1-2 potential issue that I caught @shafiqihtsham

1. Instead of leaving the light mode as the default, we should actually load it depending on the browser's mode (light, dark)

I'm on Dark Mode on Chrome. I run npm start, and then the page loads in light mode.

I think we decided to leave it this way for now if i remember correctly, however, on 2nd thought, I think it makes more sense from a UX pov that if a user has their browser in dark mode already, then we should facilitate that for them automatically.

So on 2nd thought, let's actually set that up.

2. Light Mode Theme should keep the switch button with a hover effect because it blends in with the white bkg so users won't be able to see it. In order to switch in light mode to dark mode, one would have to hover over the button to see it appear.

See sreenshot 1 (top right corner) vs screenshot 2

Screenshot 1

Screenshot 2

[CryptoTotalWar]

We need to fix this.

[CryptoTotalWar]

Once These issues are solved, we can close this issue ticket as solved.

[CMCDragonkai]

It's fine to keep it only light mode. Shell commands generally don't have significant highlighting. This is extremely low priority.

25 July 2024 05:31:35 Pablo Padillo @.***>:

Once These issues are solved, we can close this issue ticket as solved.

— Reply to this email directly, view it on GitHub[https://github.com/MatrixAI/Polykey-Docs/issues/102#issuecomment-2248754249], or unsubscribe[https://github.com/notifications/unsubscribe-auth/AAE4OHIDPL5HDABXVPGAKWTZN76JJAVCNFSM6AAAAABLC5TLBOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDENBYG42TIMRUHE]. You are receiving this because you are subscribed to this thread. [Tracking image][https://github.com/notifications/beacon/AAE4OHOTMUTA3C3XZT7CCULZN76JJA5CNFSM6AAAAABLC5TLBOWGG33NNVSW45C7OR4XAZNMJFZXG5LFINXW23LFNZ2KUY3PNVWWK3TUL5UWJTUGBFCES.gif]

[CryptoTotalWar]

It's fine to keep it only light mode. Shell commands generally don't have significant highlighting. This is extremely low priority. 25 July 2024 05:31:35 Pablo Padillo @.***>: … Once These issues are solved, we can close this issue ticket as solved. — Reply to this email directly, view it on GitHub[#102 (comment)], or unsubscribe[https://github.com/notifications/unsubscribe-auth/AAE4OHIDPL5HDABXVPGAKWTZN76JJAVCNFSM6AAAAABLC5TLBOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDENBYG42TIMRUHE]. You are receiving this because you are subscribed to this thread. [Tracking image][https://github.com/notifications/beacon/AAE4OHOTMUTA3C3XZT7CCULZN76JJA5CNFSM6AAAAABLC5TLBOWGG33NNVSW45C7OR4XAZNMJFZXG5LFINXW23LFNZ2KUY3PNVWWK3TUL5UWJTUGBFCES.gif]

Switched default to light mode. Closing ticket.