chore(markdown): Avoid lines longer than 80 chars
This commit is contained in:
parent
aea0ae7e8f
commit
ed30a24a54
1 changed files with 40 additions and 13 deletions
|
@ -7,37 +7,56 @@ Some things to keep in mind when working in Markdown are:
|
|||
|
||||
## Use remark-jargon for glossary terms
|
||||
|
||||
There is no need to add a *glossary* section to documentation. We use a plugin called [remark-jargon][rj] to explain terms. Information can be found at the link.
|
||||
There is no need to add a *glossary* section to documentation.
|
||||
We use a plugin called [remark-jargon][rj] to explain terms.
|
||||
Information can be found at the link.
|
||||
|
||||
[rj]: https://github.com/freesewing/freesewing/blob/develop/packages/remark-jargon/README.md
|
||||
|
||||
## Let lists be lists
|
||||
|
||||
Please make sure to use Markdown proper, doing things such as hardcoding numbers for lists and using `·` for bulleted lists won't be rendered properly and will be styled differently. Using Markdown in the same way for everything ensures the site and documentation look clean and professional. You can use a Markdown editor like [StackEdit](https://stackedit.io/) to preview your text.
|
||||
Please make sure to use Markdown proper, doing things such as hardcoding
|
||||
numbers for lists and using `·` for bulleted lists won't be rendered
|
||||
properly and will be styled differently.
|
||||
Using Markdown in the same way for everything ensures the site and
|
||||
documentation look clean and professional. You can use a Markdown editor
|
||||
like [StackEdit](https://stackedit.io/) to preview your text.
|
||||
|
||||
<Note>
|
||||
Github itself also allows working in Markdown and will give you a handy preview!
|
||||
</Note>
|
||||
|
||||
If you get lost or have a question about how to do something, feel free to come ask on the Discord. We've all had to learn Markdown at some point and would be delighted to pass knowledge on.
|
||||
If you get lost or have a question about how to do something, feel free to come
|
||||
ask on the Discord. We've all had to learn Markdown at some point and would be
|
||||
delighted to pass knowledge on.
|
||||
|
||||
## Create meaningful links
|
||||
|
||||
When adding links please do not link them using a structure like: Link [here][yt]. Instead put the link under the relevant term. See first list item for an example.
|
||||
When adding links please do not link them using a structure like:
|
||||
Link [here][yt]. Instead put the link under the relevant term.
|
||||
See first list item for an example.
|
||||
|
||||
[yt]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
||||
|
||||
## Make sure your links lead where they think you do
|
||||
|
||||
- When you are linking within freesewing you can use a relative link from the site root.
|
||||
Think `markdown/dev/guides/markdown/frequent-mistakes` instead of `https://github.com/freesewing/freesewing/tree/develop/markdown/dev/guides/markdown/frequent-mistakes`
|
||||
- Images can be put in the same folder you are working on with a link to the filename.
|
||||
- When you are linking within freesewing you can use a relative link from
|
||||
the site root.
|
||||
Think `markdown/dev/guides/markdown/frequent-mistakes` instead of
|
||||
`https://github.com/freesewing/freesewing/tree/develop/markdown/dev/guides/markdown/frequent-mistakes`
|
||||
- Images can be put in the same folder you are working on with a link
|
||||
to the filename.
|
||||
|
||||
## Avoid ambiguity when lising a number of steps
|
||||
|
||||
If you're writing documentation that involves steps, please do not mix levels of steps. Steps written out in documentation are there to facilitate brainless execution. Don't be afraid to repeat yourself.
|
||||
If you're writing documentation that involves steps, please do not mix levels
|
||||
of steps. Steps written out in documentation are there to facilitate brainless
|
||||
execution. Don't be afraid to repeat yourself.
|
||||
|
||||
If you use substeps we want those substeps to take away ambiguity rather than introduce it into your instructions. In the next example the substep introduces something that ought to be done before the previous steps. This creates confusion about when that step ought to be executed.
|
||||
If you use substeps we want those substeps to take away ambiguity rather
|
||||
than introduce it into your instructions. In the next example the substep
|
||||
introduces something that ought to be done before the previous steps.
|
||||
This creates confusion about when that step ought to be executed.
|
||||
|
||||
An example of what not to do:
|
||||
|
||||
|
@ -49,9 +68,14 @@ If you're writing documentation that involves steps, please do not mix levels of
|
|||
|
||||
## Be mindful of whitespace
|
||||
|
||||
Markdown sytax around white space is a little unintuitive. If you want a paragraph break but no white space you need to add two spaces at the end of your line. I've found it helpful to experiment and keep checking the preview to see how things look. Not all the empty lines and whitespace in your document will render in the preview.
|
||||
Markdown sytax around white space is a little unintuitive. If you want a
|
||||
paragraph break but no white space you need to add two spaces at the end of
|
||||
your line. I've found it helpful to experiment and keep checking the preview
|
||||
to see how things look. Not all the empty lines and whitespace in your
|
||||
document will render in the preview.
|
||||
|
||||
When you're using custom components you want to leave an empty line before and after your component.
|
||||
When you're using custom components you want to leave an empty line before
|
||||
and after your component.
|
||||
|
||||
```markdown
|
||||
Lorem ipsum dolor sit amet,
|
||||
|
@ -63,7 +87,8 @@ consectetur adipisci elit,
|
|||
sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
|
||||
```
|
||||
|
||||
If you're using any markdown syntax within a custom component you want to also leave an empty line at the start and end of your component.
|
||||
If you're using any markdown syntax within a custom component you want to also
|
||||
leave an empty line at the start and end of your component.
|
||||
|
||||
|
||||
```markdown
|
||||
|
@ -79,7 +104,9 @@ sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
|
|||
```
|
||||
|
||||
## Don't be shy to ask a friend
|
||||
Learning a new language can be intimidating, whether its Javascript, Norse or Markdown but everyone in the Freesewing community is glad you're here and helping us make the site even more awesome.
|
||||
Learning a new language can be intimidating, whether its Javascript, Norse or
|
||||
Markdown but everyone in the Freesewing community is glad you're here and
|
||||
helping us make the site even more awesome.
|
||||
|
||||
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue