v1.7.0+ss22

Overview

Wow there's a lot to talk about in this Spring/Summer 2022 release. Here's a TLDR overview with links to relevant documentation:

• NEW FEATURES

  • 🖼️ Diagrams with Excalidraw & Mermaid (docs)
  • 🌙 Dark-mode images (docs)
  • 😶 Code blocks with no line numbers! (#165) (demo)

• 📝 New docs

  • "Markdown Tips" guide (#153) compiles a list of Markdown features you may not have known before!

• ⚡ Miscellaneous

  • Fixed: Headers with formatting got truncated in the Sidebar. (#160)
  • Fixed: Leading whitespace in first line of code block was trimmed. (#178)
  • Enhancement: "Copy" button in console code block only copies commands! (#169)

• Fun

  • 🍎 New logo! (#162)
  • 🎃 Limited edition Halloween theme! (#157)

• ⚠️ DEPRECATION NOTICE: useLegacyCodeBlocks configuration options will be removed in a future version of Primer Spec. Use defaultCodeblockVariant instead.

Acknowledgements

Quite a few people were involved with the changes in this release. Thank you all for your contributions, Primer Spec wouldn't be awesome without you all! 🙇

• @awdeorio and @sugihjamin / @eecs441staff for the terrific feature requests, discussions and PR validation!
• @bellakiminsun for keeping me focused via design & product-philosophy discussions 😃
• @jackphong and @marcus-darden for reporting several bugs in Primer Spec!

Last but not least, thank you course instructors and tutorial authors for using Primer Spec! Your usage of this theme keeps me motivated to continue improving Primer Spec ❤️

Feature spotlights

🖼️ Diagrams with Excalidraw & Mermaid

Excalidraw

Docs: demo/diagrams.html#excalidraw

Primer Spec recommends using excalidraw.com (or the official VSCode extension) to create free-form diagrams for use with your spec. As long as you name your images with the file extension .excalidraw.png or .excalidraw.svg, Primer Spec will automatically optimize them for users in dark mode!

Light mode	Dark mode

Mermaid

Docs: demo/diagrams.html#mermaid

If you don't prefer using Excalidraw, you can also use Mermaid. Mermaid allows you to create beautiful diagrams declaratively. GitHub recently added support for Mermaid, and you can use the same API in Primer Spec! Just remember to add mermaid: true at the top of your Markdown file.

Light mode	Dark mode

🌙 Dark-mode images

Docs: demo/images.html

When I use dark mode to read webpage, my biggest pet-peeve is that images don't change colors too.

Primer Spec now makes it ultra-easy to optimize most images for dark-mode users — just add the class invert-colors-in-dark-mode to your image element! (See the docs for exact syntax.)

Unfortunately, this doesn't work for all images. If you need fine-grained control over your images, you can even specify two different versions of your image — one optimized for light-mode and the other optimized for dark-mode! Simply add #gh-light-mode-only or #gh-dark-mode-only to the URL of each image. (See the docs for an example.)

😶 Code blocks with no line numbers!

Demo: demo/enhanced-code-blocks.html#no-line-numbers

Primer Spec "enhanced" code blocks automatically add line numbers to the code block. If you don't like the line numbers (or you think it's confusing), you can use the data-variant="no-line-numbers" attribute to hide the line numbers!

Here are screenshots of each variant:

enhanced (default)	no-line-numbers	legacy

⚠️ DEPRECATION NOTICE

useLegacyCodeBlocks configuration options will be removed in a future version of Primer Spec. Use defaultCodeblockVariant instead.