Diataxis

Getting started

Add it to your .vale.ini, then run vale sync.

Packages = Diataxis

[*.md]
BasedOnStyles = Vale, Diataxis

The name installs the latest release each time vale sync runs. To stay on v0.1.0, the release this page describes, give its URL instead:

Packages = https://github.com/jdkato/diataxis/releases/download/v0.1.0/Diataxis.zip

• Diataxis.Examples suggestion occurrence scope: raw Style guide

  Reference provides examples. There is no code block on this page.

• Diataxis.Expectations suggestion occurrence scope: summary Style guide

  Tell the learner what they will see at some point: 'You will see ...', 'Notice that ...'.

• Diataxis.Explanation suggestion existence Style guide

  '%s' opens an explanation. Keep it to the step; link to the explanation instead.

• Diataxis.Explanation suggestion existence Style guide

  '%s' opens an explanation. Keep the guide to the steps; link to the explanation.

• Diataxis.Imperative suggestion existence scope: list Style guide

  '%s' softens an instruction. Write the step as a command.

• Diataxis.Instruction warning existence scope: list Style guide

  '%s' is an instruction. Explanation discusses; put the steps in a how-to guide.

• Diataxis.Instruction error existence Style guide

  '%s' instructs or advises. Reference describes; put the guidance in a how-to guide.

• Diataxis.Opening warning occurrence scope: text & doc(h1 + p) Style guide

  Open by saying what the learner will build or be able to do by the end.

• Diataxis.Opening warning occurrence scope: text & doc(h1 + p) Style guide

  Open by saying what the guide shows the reader how to do.

• Diataxis.Opinion warning existence Style guide

  '%s' is an opinion. Reference states what is.

• Diataxis.Options warning existence Style guide

  '%s' offers a choice. A tutorial takes one path; alternatives belong in a how-to guide.

• Diataxis.Reference suggestion occurrence scope: raw Style guide

  %d tables. Explanation gives the shape; the full listing is reference, so link to it.

• Diataxis.Reference suggestion occurrence scope: raw Style guide

  %d table rows. Refer to the reference for the full list of options rather than carrying it here.

• Diataxis.Steps warning occurrence scope: doc(ol) Style guide

  A tutorial walks the learner through numbered steps; there is no numbered list here.

• Diataxis.Steps warning occurrence scope: doc(ol) Style guide

  A how-to guide is a sequence of steps; there is no numbered list here.

• Diataxis.Teaching warning existence Style guide

  '%s' is teaching. A how-to guide assumes the reader knows the basics; a tutorial teaches them.

• Diataxis.Title warning occurrence scope: heading.h1 Style guide

  Name the guide for its goal: 'How to ...' or a verb phrase such as 'Deploying to ...'.

• Diataxis.Walkthrough warning existence Style guide

  '%s' narrates. Reference states; a tutorial walks.

• Diataxis.We suggestion occurrence scope: summary Style guide

  A tutorial says 'we': the tutor is beside the learner. Nothing here does.

• Diataxis.Why suggestion occurrence scope: summary Style guide

  Explanation answers why. Nothing here says because, the reason, or in order to.