From 669b42d4052c25bd7762bbbd3d296f8f379ed9a4 Mon Sep 17 00:00:00 2001 From: Josefine Hansson Date: Mon, 19 Feb 2024 10:00:44 +0100 Subject: [PATCH] updated readme --- README.md | 53 +++++++++++++++++++---------------------------------- 1 file changed, 19 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 6319820934..fbf2b09e5e 100644 --- a/README.md +++ b/README.md @@ -8,55 +8,47 @@ The production website is available at: ## How Can I Contribute? -Contributing by creating content or suggestion changes to existing content can be done by making **pull requests**. +Contributing by creating content or suggesting changes to existing content can be done by making **pull requests**. -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. +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. -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. +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. -Once the pull request gests approved and merged into main, the content will be deployed to the live server. - -There are four different content types you can contribute with. These are **tutorial**, **article**, **how to** and **project**. Please read more on what they mean and how to write one in the [Contribution Templates folder](/contribution-templates/README.md). - -|Content|Description|Example| -|-------|-----------|-------| -|Tutorial|Learn how to do something.|[Control Built-in RGB LED over Wi-Fi with Nano RP2040 Connect](https://docs.arduino.cc/tutorials/nano-rp2040-connect/rp2040-web-server-rgb)| -|Article|Learn about a specific topic.|[Multimeter Basics](https://docs.arduino.cc/learn/electronics/multimeter-basics)| -|How To|Smaller tutorial with less information and more straight to the example.|[Analog Read Serial](https://docs.arduino.cc/built-in-examples/basics/AnalogReadSerial)| -|Project|Learn how to build something.|[Plant Communicator with MKR WiFi 1010](https://projecthub.arduino.cc/Arduino_Genuino/plant-communicator-with-mkr-wifi-1010-081cf5)| +Once the pull request gets approved and merged into main, the content will be deployed to the live server. ## Fixing Bugs and Typos -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. +If you find 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. ### Products -- If you found an issue in a hardware product-specific tutorial they are located according to the following pattern: +- If you have found an issue in a hardware product-specific tutorial they are located according to the following pattern: `/content/hardware/[product-family]/[product-type]/[product]/tutorials/[tutorial-name]/[content-file].md` -- If you found an issue in a hardware product's datasheet they are located according to the following pattern: +- If you have found an issue in a hardware product's datasheet they are located according to the following pattern: `/content/hardware/[product-family]/[product-type]/[product]/datasheet/datasheet.md` -- If you found an issue in a hardware product's description they are located according to the following pattern: +- If you have found an issue in a hardware product's description they are located according to the following pattern: `/content/hardware/[product-family]/[product-type]/[product]/product.md` -- If you found an issue in a hardware product's tech specs table they are located according to the following pattern: +- If you have found an issue in a hardware product's tech specs table they are located according to the following pattern: `/content/hardware/[product-family]/[product-type]/[product]/tech-specs.yml` -- If you found an issue in a hardware product's features they are located according to the following pattern: +- If you have found an issue in a hardware product's features they are located according to the following pattern: `/content/hardware/[product-family]/[product-type]/[product]/features.md` ### Software -- If you found an issue in a software product's tutorial they are located according to the following pattern: +- If you have found an issue in a software product's tutorial they are located according to the following pattern: `/content/software/[product-name]/tutorials/(tutorial-subfolder)/[tutorial-name]/[content-file].md` ## Adding Content ### Referencing Content From Other Folders -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. -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. +The build system supports symlinks. This allows the inclusion of 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. + +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 to the source file in both cases. #### Adding Symlinks on Windows @@ -88,24 +80,17 @@ Code snippets can be included by using the triple backticks syntax e.g. ` ```ard 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 ``` -### Including Code Blocks fetching Github pages +### Including Code Blocks fetching GitHub pages CodeBlocks are custom components that can be added directly in the Markdown on docs-content. -Using this component, the code block will be fetched directly from Github pages. -Syntax: -` ` +Using this component, the code block will be fetched directly from GitHub pages. -Broken URL will show error alert. URL must be in Github domain and must be public. +Syntax: -### Use Custom content con various component +` ` -- **Details** pages: on every `product.md` file you have to create 4 variables, related to the hero buttons component in every details page: - - primary_button_url: (string) - - primary_button_title: (string) - - secondary_button_url: (string) - - secondary_button_title: (string) -- **Video**: You can manage the content in the video components (Actually in Learn, Arduino-cloud and MycroPython page), just compiling the file `videoInfo.md` in the main directory of the relative section. +Broken URLs will show an error alert. URL must be in the GitHub domain and must be public. ## Previewing Changes