Skip to content

Commit

Permalink
000: split style guide from template
Browse files Browse the repository at this point in the history 
This change adds some features to the repo's style guide:

- folding long content
- info blocks
- multiple authors

It also adds a new markdown template, which uses each element mentioned
in the style guide, but doesn't explain them. This should allow for
easier copy-and-adapt use by authors, as the styles guide's dual,
pre-and-post-rendered view of each element doesn't lend itself to being
copied and then edited inline.

Signed-off-by: Jonathan Matthews <github@hello.jonathanmatthews.com>
  • Loading branch information
@jpluscplusm
jpluscplusm committed Oct 24, 2023
1 parent 1c270cc commit 1552cc5
Show file tree
Hide file tree
Showing 3 changed files with 204 additions and 24 deletions.
129 changes: 106 additions & 23 deletions 000_template/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Template
# Style Guide

Please use this file as a template and guide for new cue-by-example documents.
Use this file as a style guide when creating new cue-by-example documents, and
use the file [template.md](template.md) as a template you can copy and adapt.

## Conventions

Expand All @@ -9,24 +10,26 @@ Please use this file as a template and guide for new cue-by-example documents.
Use a single H1 heading (`#`), at the top, to indicate the document's title.

On the Markdown line directly underneath the H1 line, include a `<sup>` HTML
element containing your preferred attribution as the document author. For
example:
element containing your preferred attribution as the document author, and for
each co-author. For example:

---

```
# Using CUE to get ahead in Hollywood
<sup>by [George Clooney](https://www.imdb.com/name/nm0000123/)
<sup>by [George Clooney](https://www.imdb.com/name/nm0000123/)</sup>
<sup>and [Halle Berry](https://www.imdb.com/name/nm0000932/)</sup>
```

---

which renders as:
... which renders as:

---

# Using CUE to get ahead in Hollywood
<sup>by [George Clooney](https://www.imdb.com/name/nm0000123/)
<sup>by [George Clooney](https://www.imdb.com/name/nm0000123/)</sup>
<sup>and [Halle Berry](https://www.imdb.com/name/nm0000932/)</sup>

---

Expand Down Expand Up @@ -77,7 +80,7 @@ Please include at a minimum:

### Files

Please indicate each file that the user should create:
Indicate each file that the user should create:

- with a :floppy_disk: icon (`:floppy_disk:`)
- followed on the same line by the file's path and name in an inline code block
Expand Down Expand Up @@ -108,13 +111,9 @@ some_content: "some string"
```
---

#### Folding large files

TODO

### Shell commands
### Shell command blocks

Please indicate one or more commands that the user should run in a shell:
Indicate one or more commands that the user should run in a shell:

- with a :computer: icon (`:computer:`)
- followed on the same line by the word `terminal` in an inline code block
Expand All @@ -129,9 +128,9 @@ automatically places at the top right of each code block will give the reader
useful, paste-able text. If you were to include a prefix, such as `$`, then the
reader wouldn't be able to paste the commands directly into a terminal.

Please include example output in a separate fenced code block, after the
command code block, to help the user judge if the command has run as expected
on their local machine.
Include example output in a separate fenced code block, after the command code
block, to help the user judge if the command has run as expected on their local
machine.

For example:

Expand Down Expand Up @@ -171,18 +170,99 @@ CUE is awesome!

---

### Warning blocks
#### Folding lengthy file or shell content

If your reader needs to be warned at a specific point in the document, use a
Markdown table as follows, with the exact heading as provided:
When a file or shell block's contents is long enough that it disrupts the flow
of the guide, consider placing the lengthy content inside a "click-to-expand"
`<details>` HTML element.

---
This element has 2 parts:

- a short preable that's always visible (the `<summary>`)
- the folded content that's only visible after a click

Please use the folding element as follows:

- Place the element inside a pair of horizontal lines (`<hr>`), to indicate to
the reader where the unfolded content finishes
- Wrap the file's name in a `<code>` element (instead of single backticks)
- Follow the file's name with the words `(click to open)`
- Place a blank (source) line between the closing `</summary>` tag and the
opening of the file's fenced code block (<code>```</code>), so that GitHub's
markdown formatting works correctly

Here's an example of using a `<details>` element to fold a file:

````
Here's a file that you might find useful:
<hr>
<details>
<summary>
:floppy_disk: <code>a_file.cue</code> (click to open)
</summary>
```text
A
long
file
but
not
really
as
this
is
just
an
example
```
</details>
<hr>
````

| :exclamation: WARNING :exclamation: |
|:--------------------------------------- |
This renders as follows:

Here's a file that you might find useful:

<hr>
<details>
<summary>
:floppy_disk: <code>a_file.cue</code> (click to open)
</summary>

```text
A
long
file
but
not
really
as
this
is
just
an
example
```
</details>
<hr>

### Warning and Info blocks

If your reader needs to be warned or informed at a specific point in the
document, use a Markdown table like one of the following, with one of the
headings exactly as provided:

---

```
| :exclamation: WARNING :exclamation: |
|:----------------------------------- |
| This warning text must appear on a single line in the markdown source, as if there's a line break then the formatting will break. Whilst this can result in unwieldy source text, the rendered result looks fine. To force a line break, use an HTML `<br>` tag, like this:<br> To force a blank line use two, like this:<br><br> This source line, unlike the 2 above it, **doesn't** need to end with a pipe symbol. Most markdown formatting elements work correctly in tables, such as [links](https://example.com), *italic*, **bold**, and `inline code blocks`. Anything with multiple lines, such as fenced code blocks, probably won't work.
| :grey_exclamation: Info :grey_exclamation: |
|:------------------------------------------ |
| This Info block is less "shouty" than the WARNING, above. All the formatting and content notes in the WARNING example also apply here.
```

---
Expand All @@ -195,4 +275,7 @@ This renders as follows:
|:--------------------------------------- |
| This warning text must appear on a single line in the markdown source, as if there's a line break then the formatting will break. Whilst this can result in unwieldy source text, the rendered result looks fine. To force a line break, use an HTML `<br>` tag, like this:<br> To force a blank line use two, like this:<br><br> This source line, unlike the 2 above it, **doesn't** need to end with a pipe symbol. Most markdown formatting elements work correctly in tables, such as [links](https://example.com), *italic*, **bold**, and `inline code blocks`. Anything with multiple lines, such as fenced code blocks, probably won't work.

| :grey_exclamation: Info :grey_exclamation: |
|:------------------------------------------ |
| This Info block is less "shouty" than the WARNING, above. All the formatting and content notes in the WARNING example also apply here.
---
96 changes: 96 additions & 0 deletions 000_template/template.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Writing cue-by-example guides
<sup>by [Jonathan Matthews](https://jonathanmatthews.com/)</sup>
<sup>and [Paul Jolly](https://myitcv.io/)</sup>

Use this file as a template when creating new cue-by-example guides.

## Introduction

This introduction explains the broad context of this guide, what technologies
it deals with, and what prerequisites the reader must be aware of to use the
guide successfully.

### Prerequisites

To use this guide, you need to:

- [install the `cue` command](https://alpha.cuelang.org/docs/introduction/installation/)
- and perhaps do some other things, as well

## Scenario A-1

This scenario can be read in isolation from any other scenario.

| :grey_exclamation: Info :grey_exclamation: |
|:------------------------------------------ |
| A scenario can build on the learnings imparted by other scenarios.<br><br>However, if its steps *cannot* be carried out without first completing another scenario, then consider merging the two scenarios into one.

### Create some files

This section is a container for the following 2 steps.

#### :arrow_right: Create `cue_file_1.cue`

:floppy_disk: `cue_file_1.cue`
```CUE
package foo
some_content: "some string"
some_boolean: true
```

#### :arrow_right: Create `really_long_file.txt`

<hr>
<details>
<summary>
:floppy_disk: <code>really_long_file.txt</code> (click to open)
</summary>

```text
A
long
file
but not
really long.
```
</details>
<hr>

### Do something with the files

#### :arrow_right: Audit the files

Count the lines in each file by running:

:computer: `terminal`
```sh
wc -l *
```

Expected output:
```
4 cue_file_1.cue
5 really_long_file.txt
9 total
```

| :exclamation: WARNING :exclamation: |
|:----------------------------------- |
| The file `really_long_file.txt` is not, in fact, really long. This is a known weakness of [this guide](template.md).<br><br>Please feel free to open [an issue](/issues/new/choose) to track this problem.

## Scenario B-2

This is a very short scenario, which can be read separately from
[Scenario A-1](#scenario-a-1).

## Conclusion

This section concludes the guide by:

- reminding the reader about the significant elements of what they've achieved
in the guide's different scenarios,
- reminding the reader why the scenarios' outcomes were useful,
- reenforcing any important reminders or warnings, and
- pointing to any additional guides or sites that might be useful to develop
the reader's learning further.
3 changes: 2 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ integrating with 3rd-party tools, services, and systems.

## Contributing

Please use [`000_template/README.md`](000_template/README.md) as a template when
First please read the [style guide](000_template/README.md), and then use
[000_template/template.md](000_template/template.md) as a template when
contributing additional guides to this repo.

## Contribution guidelines
Expand Down

0 comments on commit 1552cc5

Please sign in to comment.