Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhance Hugo Syntax Definitions and Examples #41

Open
tajmone opened this issue Dec 1, 2019 · 0 comments
Open

Enhance Hugo Syntax Definitions and Examples #41

tajmone opened this issue Dec 1, 2019 · 0 comments
Labels
💡 enhancement A new feature or enhancement request 🕑 pending decision Issue requires decisions by maintainers ⭐ css Topic: Custom stylesheets ⚠️ useful Priority: Low
Milestone

Comments

@tajmone
Copy link
Owner

tajmone commented Dec 1, 2019

  • POSTPONEDThis enhancement is postponed after the 1st release of the book.
  • UNCOFIRMEDStill needs testing and evaluation before giving the green light.

Hugo Syntax definitions are not syntax highlighted, they are just literal blocks (see #35) with a custom role (literal, role="hugosyntax") to allow custom styling via CSS (or other means, in different output formats).

The block is styled using the Base2Tone Lake colour scheme by Bram de Haan, which provides 4 base hues available in eight tints variations. Currently we are using just two colours: background and foreground.

We could enhance Hugo syntax definitions by using different colours for keywords, parameters. comments and surrounding code, as well as the various token indicating optionality ([]), alternatives (|) and omissions (...).

But this would require manual implementation by using a combination of bold, italic and custom styles via the [style]#text# notation — or even exploiting classes on bold and italics via the [.style]*text* notation (See §10.5.6. Role » Inline Assignment in Asciidoctor Manual).

It's important here to think carefully on how the document will be rendered by other people targeting different formats or using different templates. The final document must look nice independently of the template and stylesheet employed. Therefore, it's better to use a styling notation that would not affect the visual appearance of the document in other toolchains, but at the same time use a system that allows to enforce these intended styles also across other formats and backends.

Possibly, using bold for styling the keywords that are central to the syntax definition (or syntax example) should be acceptable for it would always provide an acceptable styling across al formats and templates.

As for customization of the additional symbols for optionality, etc., it might be wiser to use custom roles that would not affect visually those elements in non-dedicate templates, just to be on the safe side.

I need to experiment with this first.

@tajmone tajmone added 💡 enhancement A new feature or enhancement request ⚠️ useful Priority: Low 🕑 pending decision Issue requires decisions by maintainers ⭐ css Topic: Custom stylesheets labels Dec 1, 2019
@tajmone tajmone added this to the hugo code milestone Dec 1, 2019
@tajmone tajmone pinned this issue Dec 1, 2019
@tajmone tajmone unpinned this issue Dec 22, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
💡 enhancement A new feature or enhancement request 🕑 pending decision Issue requires decisions by maintainers ⭐ css Topic: Custom stylesheets ⚠️ useful Priority: Low
Projects
None yet
Development

No branches or pull requests

1 participant