|
1 | 1 | # docs-content |
2 | 2 |
|
3 | | -Content for docs.arduino.cc |
| 3 | +## What Is this Repository? |
| 4 | + |
| 5 | +This repository hosts the content for Arduino's documentation website. The content needs to be written in Markdown and will be converted to HTML automatically during the build process. |
| 6 | + |
| 7 | +The production website is available at: <https://docs.arduino.cc> |
| 8 | + |
| 9 | +## How Can I Contribute? |
| 10 | + |
| 11 | +Contributing by creating content or suggestion changes to existing content can be done by making **pull requests**. |
| 12 | +You start by forking the repository or by creating a new branch if you have write access to this repo. Create a new branch based on main and name it according to what you will create prefixed with your github username and a slash (e.g. `sebromero/wifi-tutorial`). Read in the section below how to add different types of new content. |
| 13 | + |
| 14 | +When you're done with a draft you can create a pull request. This will give the content team the possibility to review it and leave comments or request changes. During this review process you can continue to push commits to the same branch. They will show up in the pull request automatically. |
| 15 | +Once the pull request gests approved and merged into main, the content will be deployed to the live server. |
| 16 | + |
| 17 | +## Fixing Bugs and Typos |
| 18 | + |
| 19 | +If you found a mistake in the content you need to locate the corresponding file to fix it and create a pull request. Here is how to locate the content. |
| 20 | + |
| 21 | +### Products |
| 22 | + |
| 23 | +- If you found an issue in a hardware product-specific tutorial they are located according to the following pattern: |
| 24 | + `/content/hardware/[product-family]/[product-type]/[product]/tutorials/[tutorial-name]/[content-file].md` |
| 25 | + |
| 26 | +- If you found an issue in a hardware product's datasheet they are located according to the following pattern: |
| 27 | + `/content/hardware/[product-family]/[product-type]/[product]/datasheet/datasheet.md` |
| 28 | + |
| 29 | +- If you found an issue in a hardware product's description they are located according to the following pattern: |
| 30 | + `/content/hardware/[product-family]/[product-type]/[product]/product.md` |
| 31 | + |
| 32 | +- If you found an issue in a hardware product's tech specs table they are located according to the following pattern: |
| 33 | + `/content/hardware/[product-family]/[product-type]/[product]/tech-specs.yml` |
| 34 | + |
| 35 | +- If you found an issue in a hardware product's features they are located according to the following pattern: |
| 36 | + `/content/hardware/[product-family]/[product-type]/[product]/features.md` |
| 37 | + |
| 38 | +### Software |
| 39 | + |
| 40 | +- If you found an issue in a sofware product's tutorial they are located according to the following pattern: |
| 41 | + `/content/software/[product-name]/tutorials/(tutorial-subfolder)/[tutorial-name]/[content-file].md` |
| 42 | + |
| 43 | +## Adding Content |
| 44 | + |
| 45 | +### Create a New Datasheet |
| 46 | + |
| 47 | +- Create a new feature branch for the datasheet using a `datasheets` prefix. E.g. `datasheets/mkr-1010` |
| 48 | +- You can collaborate with other people on the same branch. For larger changes in a multi-people collaboration setting you can create a separate branch that is based on the feature branch. e.g. `datasheets/mkr-1010-certification` based on `datasheets/mkr-1010`. |
| 49 | +- Inside the product directory e.g. `content/hardware/01.mkr/boards/mkr-wifi-1010` create a folder named `datasheet` for the new datasheet |
| 50 | +- In your newly created folder create the `datasheet.md` file that will contain the content of the datasheet. |
| 51 | +- Create a subfolder called `assets` where you put all the images that are used in the datasheet. |
| 52 | +- Images that purely consist of illustrations should be in SVG format binary images in PNG format. **Make sure to outline the text for SVG exports**. Both Figma and Illustrator provide this option in their file export settings. |
| 53 | +- When you're done with a section of the datasheet that was worked on in a specific branch e.g. `datasheets/mkr-1010-certification` create a Pull Request to merge that branch back into the original feature branch e.g. `datasheets/mkr-1010-certification` -> `datasheets/mkr-1010`. Request a review from the responsible person for this datasheet creation task or additional people from whome you need confirmation on correctness (e.g. from the hardware/firmware team). |
| 54 | +- When you're done with the complete datasheet and you want to merge it back into main, create a pull request e.g. `datasheets/mkr-1010` -> `main`. The build process will create a PDF from the datasheet that will be deployed automatically to the website. ⚠️ This will only work if the branch name contains `datasheet` or `datasheets` in its name, and the PR is not created from a fork. |
| 55 | + Request a review from the responsible person for this datasheet creation task or additional people from whome you need confirmation on correctness (e.g. from the hardware/firmware team). |
| 56 | +- Make sure to preview the datasheet in its rendered form while you're working on it to check for visual glitches. You can do so using the datasheet generator tool. |
| 57 | + |
| 58 | +### Linking a Datasheet to a Product |
| 59 | + |
| 60 | +If the datasheet is created from markdown and put inside the `datasheet` folder it shows up on the product page automatically. **IMPORTANT:** In order to speed up the preview builds, the datasheets will only be generated if the branch name contains `datasheet` or when the changes are merged back to the `main` branch. You can also set a `url_datasheet` property in the frontmatter part of a product page (product.md) which points to a URL. For the datasheet button in the product page header, the URL will take precedence over the generated datasheet. In the downloads section only the generated datsheets appear. |
| 61 | + |
| 62 | +### Adding a new Product Family |
| 63 | + |
| 64 | +To add a new family of products, create a new folder under `/content/hardware/`. Please note that the sorting is based on the family name. Therefore, if you need a specific sorting, prepend the name with a number (e.g. 05.nicla). |
| 65 | +Inside that folder create a file named `family.md` and fill in the following contents: |
| 66 | + |
| 67 | +``` |
| 68 | +--- |
| 69 | +title: Family Name |
| 70 | +description: Description of that product family |
| 71 | +--- |
| 72 | +``` |
| 73 | + |
| 74 | +The new family will only show up if it contains at least one product. |
| 75 | + |
| 76 | +### Adding a new Product |
| 77 | + |
| 78 | +#### Features |
| 79 | + |
| 80 | +To add features to a product, a `features.md` file needs to be created in the root folder of a product. |
| 81 | +To list the features the `Feature` tag can be used. The list of features needs to be wrapped inside a `<FeatureList></FeatureList>` tag pair. E.g. `<FeatureList><Feature title="Raspberry Pi RP2040 Microcontroller" image="chip"></FeatureList>`. |
| 82 | + |
| 83 | +Each feature can have one of the following icons: |
| 84 | + |
| 85 | +| name | icon | |
| 86 | +| ------------------ | --------------------------------------------------------- | |
| 87 | +| bluetooth |  | |
| 88 | +| camera |  | |
| 89 | +| cellular |  | |
| 90 | +| color-sensor |  | |
| 91 | +| communication |  | |
| 92 | +| configurability |  | |
| 93 | +| connection |  | |
| 94 | +| core |  | |
| 95 | +| crypto-chip |  | |
| 96 | +| file-icon |  | |
| 97 | +| humidity-sensor |  | |
| 98 | +| hw-pin |  | |
| 99 | +| imu |  | |
| 100 | +| led |  | |
| 101 | +| light-sensor |  | |
| 102 | +| location |  | |
| 103 | +| magnetometer |  | |
| 104 | +| mcu |  | |
| 105 | +| mega-form-factor |  | |
| 106 | +| microphone |  | |
| 107 | +| mkr-form-factor |  | |
| 108 | +| nano-form-factor |  | |
| 109 | +| nicla-form-factor |  | |
| 110 | +| power |  | |
| 111 | +| pressure-sensor |  | |
| 112 | +| proximity-sensor |  | |
| 113 | +| python |  | |
| 114 | +| sim-card |  | |
| 115 | +| temperature-sensor |  | |
| 116 | +| uno-form-factgor |  | |
| 117 | +| usb |  | |
| 118 | +| uv-sensor |  | |
| 119 | +| wifi-bluetooth |  | |
| 120 | +| wifi |  | |
| 121 | +| world-map |  | |
| 122 | + |
| 123 | +### Add Certifications |
| 124 | + |
| 125 | +The certifications for each product can be added in the frontmatter of a product in the `product.md` (e.g. `certifications: [FCC, CE, RoHS]`) and the PDF can be added to the corresponding product’s `certifications` directory. The naming should be as follows <SKU>_<CERTIFICATION>_<CATEGORY>.pdf e.g. `ABX00023_FCC_DTS.pdf` |
| 126 | + |
| 127 | +### Including Code Snippets |
| 128 | + |
| 129 | +Code snippets can be included by using the triple backticks syntax e.g. ` ```arduino` followed by the code and three closing backticks. The following syntaxes are supported: |
| 130 | + |
| 131 | +arduino, bash, markup, clike, c, cpp, css, css-extras, javascript, jsx, js-extras, coffeescript, diff, git, go, graphql, handlebars, json, less, makefile, markdown, objectivec, ocaml, python, reason, sass, scss, sql, stylus, tsx, typescript, wasm, yaml |
| 132 | + |
| 133 | +### Referencing Content From Other Folders |
| 134 | + |
| 135 | +The build system supports symlinks. This allows to include content in multiple places. For example, if there is a tutorial that works for different boards, it can be written once and included in different places. On Unix the `ln` command can be used for that. |
| 136 | +For example, if we want a tutorial that lives here `content/tutorials/generic/basic-servo-control` to show up on the Nano 33 BLE product page, we can link it as follows. First open a shell and navigate to the tutorials folder of the product. e.g. `cd content/hardware/03.nano/boards/nano-33-ble/tutorials/`. Then create a symlink with a relative path to the tutorial. e.g. `ln -s ../../../../../tutorials/generic/basic-servo-control basic-servo-control`. This will create a symbolic link to that directory without duplicating it. Any change can be made in either location. They will be applied the original source file in both cases. |
| 137 | + |
| 138 | +#### Adding Symlinks on Windows |
| 139 | + |
| 140 | +To create symlinks using Windows OS, follow the below steps: |
| 141 | + |
| 142 | +- Start a terminal (CMD) as admin. |
| 143 | +- Navigate to the folder you want the symlinks. For example, to create a link for the UNO board, navigate to `docs.arduino.cc\content\hardware\02.hero\boards\uno-rev3\tutorials`. |
| 144 | +- To create a symlink, you will need to run a command akin to: |
| 145 | + |
| 146 | +```cmd |
| 147 | +mklink AnalogInput "..\..\..\..\..\built-in-examples\03.analog\AnalogInput" |
| 148 | +``` |
| 149 | + |
| 150 | +> The `..\..\` needs to match the location of the original file. Each `..\` is a step up the directory. |
| 151 | +
|
| 152 | +Note that when creating the symlink, you will not see a file in VS code, but when you commit changes it will be recognized. |
| 153 | + |
| 154 | +On success, the following is printed: |
| 155 | + |
| 156 | +```cmd |
| 157 | +symbolic link created for AnalogInput <<===>> ..\..\..\..\..\built-in-examples\03.analog\AnalogInput |
| 158 | +``` |
| 159 | + |
| 160 | +## Previewing Changes |
| 161 | + |
| 162 | +Whenever you create a Pull Request (PR) GatsbyCloud will create a preview deployment in which you can see how your changes look when rendered on the website. The link to the preview will appear in the comments of the PR. This also works with Draft PRs, but not for PRs created from a fork. |
0 commit comments