Epic: quarto.org Style Guide

Open
#9,098 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Stale
Tech stack
yaml
Domain
documentation

Research direction

Start by reviewing the listed style questions and the linked issues 6220 and 6161, then consult the internally hosted Posit documentation style guide referenced in the issue. Define the quarto.org conventions for code cells, filenames, YAML hierarchy and terminology, CSS class notation, and console or terminal prompts; done means the style guide is documented and the related checklist items are resolved.

Written by the indexing model from the issue text.

Description

documentation epic

Are there smaller changes that we could make globally on the website that would make user’s lives easier?

  • Use code language (e.g. no bare ``` code cells) for every code cell
  • Make more use of filename to disambiguate context
  • Always include all parents of keys in YAML chunks (or a guide on when it is OK to only use a partial hierarchy)
  • When should the --- be included in a YAML header chunk?
  • What do we call YAML keys (keys or options)?
  • Do we talk about .class or class?
  • Do we include prompt characters e.g.> on R Console, or $ on Terminal?

There is a style guide (internally hosted on Confluence) for the docs for Posit's pro products. This could be referenced for most general matters. The style guide for quarto.org would focus on how we talk about Quarto, and conventions used in the source for quarto.org.

Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/quarto-cli

All issues in quarto-dev/quarto-cli

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.