|
| 1 | +# Contributing to the EDOT docs |
| 2 | + |
| 3 | +## Writing the docs |
| 4 | + |
| 5 | +We write the docs in regular markdown. |
| 6 | + |
| 7 | +The site rendering uses the [Just the Docs Jekyll theme](https://just-the-docs.com/). |
| 8 | + |
| 9 | +### Structuring the docs |
| 10 | + |
| 11 | +All docs must be written in the `./docs` directory. |
| 12 | + |
| 13 | +The docs are currently split into three navigation sections: |
| 14 | + |
| 15 | +- default section (no dedicated directory) |
| 16 | +- EDOT Collector (`_edot-collector` dir) |
| 17 | +- EDOT SDKs (`_edot-sdks` dir) |
| 18 | + |
| 19 | +Each markdown file results in a separate page. |
| 20 | + |
| 21 | +Docs pages can be structured hierarchically by using the `parent`, `grand_parent` and `nav_order` properties in the front matter sections in the markdown files: |
| 22 | + |
| 23 | +``` |
| 24 | +--- |
| 25 | +title: My Page Title |
| 26 | +layout: default |
| 27 | +nav_order: 2 |
| 28 | +parent: Use Cases |
| 29 | +--- |
| 30 | +``` |
| 31 | + |
| 32 | +- `title`: Is the page title shown in the navigation bar. This title is also being used to build hierarchies using the `parent` (and `grand_parent`) properties. |
| 33 | +- `layout`: That property must be set to the value `default` on all markdown files, otherwise the layout might break. |
| 34 | +- `nav_order`: That defines the position of the page in the navigation within it's parent context. |
| 35 | +- `parent`: Put the title of the parent page here to build a hierarchical structure of your docs pages. You can omit that property if the page should at the top level of the corresponding navigation section. |
| 36 | +- `grand_parent`: Use this property to set the grandparent, when the parent title is not unique within a navigation section. |
| 37 | + |
| 38 | +You can find more information in the [Just the Docs theme documentation](https://just-the-docs.com/docs/navigation/main/order/). |
| 39 | + |
| 40 | +### Linking other pages |
| 41 | + |
| 42 | +You can use relative links when linking other pages within the docs. Howewver, please make sure to not use the file suffix `.md` in the links: |
| 43 | + |
| 44 | +**Correct:** |
| 45 | + |
| 46 | +```markdown |
| 47 | +[My Link Text](./relativ/path/to/other_page) |
| 48 | +``` |
| 49 | + |
| 50 | +**Incorrect:** |
| 51 | + |
| 52 | +```markdown |
| 53 | +[My Link Text](./relativ/path/to/other_page.md) |
| 54 | +``` |
| 55 | + |
| 56 | +### Adding Callouts |
| 57 | + |
| 58 | +In this theme we have defined two types of callouts: `NOTE` and `WARNING`. |
| 59 | +You can use those by putting a `{: .note }` or `{: .warning }` in front of a paragraph: |
| 60 | + |
| 61 | +```markdown |
| 62 | +{: .note } |
| 63 | +My Note paragraph with some text. |
| 64 | +``` |
| 65 | + |
| 66 | +For multi-paragraph callouts use the block syntax: |
| 67 | + |
| 68 | +```markdown |
| 69 | +{: .warning } |
| 70 | +> My first warning paragraph. |
| 71 | +> |
| 72 | +> My second warning paragraph. |
| 73 | +``` |
| 74 | + |
| 75 | +## Building and previewing the docs site locally |
| 76 | + |
| 77 | +### Prerequisites |
| 78 | + |
| 79 | +1. Install Ruby. For more information, see [Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/) in the Ruby documentation. |
| 80 | +2. Install Bundler. For more information, see [Bundler](https://bundler.io/). |
| 81 | + |
| 82 | +### Preview the docs locally |
| 83 | + |
| 84 | +Initially, install the dependencies: |
| 85 | + |
| 86 | +```bash |
| 87 | +bundle install |
| 88 | +``` |
| 89 | + |
| 90 | +Run the site locally: |
| 91 | + |
| 92 | +```bash |
| 93 | +bundle exec jekyll serve |
| 94 | +``` |
| 95 | + |
| 96 | +Access your local site under http://localhost:4000/opentelemetry/ |
0 commit comments