@hyperlane-xyz/core
Version:
Core solidity contracts for Hyperlane
54 lines (37 loc) • 1.93 kB
Markdown
# Markdown Style Guide
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
- [Linting](#linting)
- [Links](#links)
- [Glossary](#glossary)
- [Internal (In-File) Links](#internal-in-file-links)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Linting
Respect the [linting rules] (you can run the linter with `yarn lint`).
Notably:
- lines should be < 120 characters long
- in practice, some of our files are justified at 100 characters, some at 120
[linting rules]: linting.md#markdown
## Links
In general:
- Use link references preferentially.
- e.g. `[my text][link-ref]` and then on its own line `[link-ref]: https://mylink.com`
- e.g. `[my text]` and then on its own line: `[my text]: https://mylink.com`
- exceptions: where it fits neatly on a single line, in particular in lists of links
- Excepted for internal and glossary links (see below), add the link reference definition directly
after the paragraph where the link first appears.
### Glossary
- Use links to the [glossary] liberally.
- Include the references to all the glossary links at the top of the file, under the top-level
title.
- A glossary link reference should start with the `g-` prefix. This enables to see what links to the
glossary at a glance when editing the specification.
- e.g. `[g-block]: glossary.md#block`
- Example: [Rollup Node Specification source][rollup-node]
[glossary]: ../glossary.md
[rollup-node]: https://raw.githubusercontent.com/ethereum-optimism/optimistic-specs/main/specs/rollup-node.md
## Internal (In-File) Links
If linking to another heading to the same file, add the link reference directly under that heading.
This makes it easier to keep the heading and the link in-sync, and signals that the heading is being
linked to from elsewhere.