From 3bb8088fc21d42d4fdd49364eeb1147dc93f4ccb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Gigandet?= Date: Fri, 7 Nov 2025 13:10:51 +0100 Subject: [PATCH] fix: internal links some-doc.md -> some-doc/ --- .github/workflows/update-dev-docs.yml | 9 +++++++++ .../(docs)/api/aws-images-dataset.mdx | 2 +- .../(docs)/api/how-to-download-images.mdx | 6 +++--- .../docs/Product-Opener/(docs)/api/index.mdx | 16 ++++++++-------- .../ref-api-and-product-schema-change-log.mdx | 2 +- .../(docs)/api/ref-cheatsheet.mdx | 4 ++-- .../(docs)/api/tutorial-dev-journey.mdx | 18 +++++++++--------- .../(docs)/api/tutorial-off-api.mdx | 4 ++-- .../tutorial-uploading-photo-to-a-product.mdx | 4 ++-- .../api/tutorials/adding-missing-products.mdx | 12 ++++++------ ...g-a-local-cache-of-open-food-facts-data.mdx | 4 ++-- .../get-ingredient-related-analysis.mdx | 6 +++--- .../api/tutorials/get-the-green-score.mdx | 2 +- ...g-cosmetics-pet-food-and-other-products.mdx | 2 +- .../(docs)/dev/explain-pro-dev-setup.mdx | 4 ++-- .../(docs)/dev/explain-user-management.mdx | 2 +- .../dev/how-to-develop-producer-platform.mdx | 6 +++--- .../(docs)/dev/how-to-develop-using-docker.mdx | 4 ++-- .../(docs)/dev/how-to-quick-start-guide.mdx | 18 +++++++++--------- .../(docs)/dev/how-to-use-gitpod.mdx | 8 ++++---- .../(docs)/dev/how-to-use-repl.mdx | 2 +- .../(docs)/dev/how-to-use-vscode.mdx | 4 ++-- .../(docs)/dev/how-to-write-and-run-tests.mdx | 2 +- .../docs/Product-Opener/(docs)/dev/index.mdx | 8 ++++---- .../(docs)/dev/ref-docker-commands.mdx | 2 +- .../Product-Opener/(docs)/dev/ref-perl.mdx | 2 +- content/docs/Product-Opener/(docs)/index.mdx | 4 ++-- scripts/generate-docs.mjs | 11 +++++++++++ 28 files changed, 94 insertions(+), 74 deletions(-) diff --git a/.github/workflows/update-dev-docs.yml b/.github/workflows/update-dev-docs.yml index bafcc70..535905c 100644 --- a/.github/workflows/update-dev-docs.yml +++ b/.github/workflows/update-dev-docs.yml @@ -191,6 +191,15 @@ jobs: find content/docs -name "*.mdx" -exec sed -i 's/^``` \+\(\w\+=.\+\)$/```text \1/' {} \; echo "Code block titles fixed" + - name: Fix internal links + run: | + echo "Fixing internal links from .md to directory format..." + # Change internal links from .md extension to directory format for the docs site + # e.g., /docs/Product-Opener/dev/how-to-develop-using-docker.md -> /docs/Product-Opener/dev/how-to-develop-using-docker/ + # Works with any link ending in .md that doesn't contain :// (excludes http/https) + find content/docs -name "*.mdx" -exec sed -i '/:\/\//! s|\([^)]*\)\.md|\1/|g' {} \; + echo "Internal links fixed" + - name: Copy documentation assets run: | echo "Copying Product Opener assets..." diff --git a/content/docs/Product-Opener/(docs)/api/aws-images-dataset.mdx b/content/docs/Product-Opener/(docs)/api/aws-images-dataset.mdx index d69fe46..bddb6db 100644 --- a/content/docs/Product-Opener/(docs)/api/aws-images-dataset.mdx +++ b/content/docs/Product-Opener/(docs)/api/aws-images-dataset.mdx @@ -12,7 +12,7 @@ Data is synchronized monthly between the Open Food Facts server and the bucket; as such some recent images are likely missing. You should not assume all images are present in the bucket. -To know the bucket key associated with an image, we use the same directory structure as on Product Opener. See [How to download images](./how-to-download-images.md#computing-single-product-image-folder) for more information. +To know the bucket key associated with an image, we use the same directory structure as on Product Opener. See [How to download images](./how-to-download-images/#computing-single-product-image-folder) for more information. For example, for the product with barcode '4012359114303', the directory containing the image is `/401/235/911/4303` (that is, three groups of 3 digits followed by one group of 4 digits, all four groups being prefixed with a `/`). diff --git a/content/docs/Product-Opener/(docs)/api/how-to-download-images.mdx b/content/docs/Product-Opener/(docs)/api/how-to-download-images.mdx index 5a6afd9..75a28d0 100644 --- a/content/docs/Product-Opener/(docs)/api/how-to-download-images.mdx +++ b/content/docs/Product-Opener/(docs)/api/how-to-download-images.mdx @@ -8,11 +8,11 @@ wish to achieve. If you want to download a few images (say up to 10), especially if these images have been uploaded recently, you should [download the image from the Open Food Facts -server](./how-to-download-images.md#download-from-open-food-facts-server). +server](./how-to-download-images/#download-from-open-food-facts-server). If you plan to download more images, you should instead [use the Open Food Facts images dataset hosted on -AWS](./how-to-download-images.md#download-from-aws). +AWS](./how-to-download-images/#download-from-aws). **NOTE:** please avoid fetching full image if it is not needed, but use image in the right size. @@ -21,7 +21,7 @@ AWS](./how-to-download-images.md#download-from-aws). If you want to download many images, this is the recommended option, as AWS S3 is faster and allows concurrent download, unlike the Open Food Facts server, where you should preferably download images one at a -time. See [AWS Images dataset](./aws-images-dataset.md) for more information +time. See [AWS Images dataset](./aws-images-dataset/) for more information about how to download images from the AWS dataset. ## Download from Open Food Facts server diff --git a/content/docs/Product-Opener/(docs)/api/index.mdx b/content/docs/Product-Opener/(docs)/api/index.mdx index 58e120e..9eb4be4 100644 --- a/content/docs/Product-Opener/(docs)/api/index.mdx +++ b/content/docs/Product-Opener/(docs)/api/index.mdx @@ -58,7 +58,7 @@ If these limits are reached, we reserve the right to deny you access to the webs If your requests come from your users directly (ex: mobile app), the rate limits apply per user. -If you need to fetch a significant fraction of the database, we recommend [downloading the data as a CSV or JSONL file directly](https://world.openfoodfacts.org/data). If you need to download images in bulk, we [have a guide for that](./how-to-download-images.md). +If you need to fetch a significant fraction of the database, we recommend [downloading the data as a CSV or JSONL file directly](https://world.openfoodfacts.org/data). If you need to download images in bulk, we [have a guide for that](./how-to-download-images/). ### If your users do not expect a result immediately (e.g., Inventory apps) @@ -126,15 +126,15 @@ We however ask that you send the [`app_name`, `app_version` and `app_uuid` param We are building a complete OpenAPI reference. Here is a list of the current API documentation available: -- [OpenAPI documentation (v2)](../api/ref-v2.md) -- [OpenAPI documentation for v3](../api/ref-v3.md) (under active development, may change frequently) -- A [cheatsheet](../api/ref-cheatsheet.md) listing some common patterns. -- A [change log for the API and product schema](../api/ref-api-and-product-schema-change-log.md) +- [OpenAPI documentation (v2)](../api/ref-v2/) +- [OpenAPI documentation for v3](../api/ref-v3/) (under active development, may change frequently) +- A [cheatsheet](../api/ref-cheatsheet/) listing some common patterns. +- A [change log for the API and product schema](../api/ref-api-and-product-schema-change-log/) ## Tutorials -- A comprehensive introduction to [Using the Open Food Facts API](tutorial-off-api.md). -- [Uploading images to the Open Food Facts API](tutorial-uploading-photo-to-a-product.md) +- A comprehensive introduction to [Using the Open Food Facts API](tutorial-off-api/). +- [Uploading images to the Open Food Facts API](tutorial-uploading-photo-to-a-product/) ## Help @@ -147,7 +147,7 @@ We are building a complete OpenAPI reference. Here is a list of the current API [slack_url]: https://slack.openfoodfacts.org/ [report_bugs]: https://github.com/openfoodfacts/openfoodfacts-server/issues/new/choose -[contribution_guidelines]: https://github.com/openfoodfacts/openfoodfacts-server/blob/main/CONTRIBUTING.md +[contribution_guidelines]: https://github.com/openfoodfacts/openfoodfacts-server/blob/main/CONTRIBUTING/ ## SDKs diff --git a/content/docs/Product-Opener/(docs)/api/ref-api-and-product-schema-change-log.mdx b/content/docs/Product-Opener/(docs)/api/ref-api-and-product-schema-change-log.mdx index 670ef1e..823d5ed 100644 --- a/content/docs/Product-Opener/(docs)/api/ref-api-and-product-schema-change-log.mdx +++ b/content/docs/Product-Opener/(docs)/api/ref-api-and-product-schema-change-log.mdx @@ -72,7 +72,7 @@ There were lots of non-breaking changes (new fields) from 2012 to 2024. Those ch ### Product version 999 - Changed barcode normalization -The normalization of leading 0s has been changed. See [Barcode normalization](./ref-barcode-normalization.md) +The normalization of leading 0s has been changed. See [Barcode normalization](./ref-barcode-normalization/) ### Product version 998 - API version 3 diff --git a/content/docs/Product-Opener/(docs)/api/ref-cheatsheet.mdx b/content/docs/Product-Opener/(docs)/api/ref-cheatsheet.mdx index 8382d6d..269cbda 100644 --- a/content/docs/Product-Opener/(docs)/api/ref-cheatsheet.mdx +++ b/content/docs/Product-Opener/(docs)/api/ref-cheatsheet.mdx @@ -4,8 +4,8 @@ title: "Reference: API CheatSheet" This reference cheatsheet gives you a quick reminder to send requests to the OFF API. -If you are new to API usage you might look at the [tutorial](tutorial-off-api.md). -Also, refer to the [API reference documentation](ref-v2.md) for complete information. +If you are new to API usage you might look at the [tutorial](tutorial-off-api/). +Also, refer to the [API reference documentation](ref-v2/) for complete information. ## Add/Edit an Existing Product diff --git a/content/docs/Product-Opener/(docs)/api/tutorial-dev-journey.mdx b/content/docs/Product-Opener/(docs)/api/tutorial-dev-journey.mdx index 2d6bc19..d6afa68 100644 --- a/content/docs/Product-Opener/(docs)/api/tutorial-dev-journey.mdx +++ b/content/docs/Product-Opener/(docs)/api/tutorial-dev-journey.mdx @@ -4,17 +4,17 @@ title: "Tutorials for Common developer journeys" ### READ only journeys -- Dev Journey : [Comparing sodas](./tutorials/comparing-sodas.md) -- Dev Journey : [Finding healthy breakfast cereals](./tutorials/finding-healthy-cereals.md) -- Dev Journey : [Scanning barcodes](./tutorials/scanning-barcodes.md) +- Dev Journey : [Comparing sodas](./tutorials/comparing-sodas/) +- Dev Journey : [Finding healthy breakfast cereals](./tutorials/finding-healthy-cereals/) +- Dev Journey : [Scanning barcodes](./tutorials/scanning-barcodes/) ### READ and WRITE journeys -- Dev Journey : [Adding missing products](./tutorials/adding-missing-products.md) -- Dev Journey : [Get the Nutri-Score](./tutorials/get-the-nutriscore.md) -- Dev Journey : [Get the Green-Score](./tutorials/get-the-green-score.md) -- Dev Journey : [Get ingredient related analysis on new or existing products (Nova, allergens, additives…)](./tutorials/get-ingredient-related-analysis.md) -- Dev Journey : [Adding non-standard fields to a food product using Folksonomy (coming soon for cosmetics, pet food, and other products)](./tutorials/folksonomy-engine.md) -- Dev Journey : [Retrieving and adding prices to products using Open Prices](./tutorials/product-prices.md) +- Dev Journey : [Adding missing products](./tutorials/adding-missing-products/) +- Dev Journey : [Get the Nutri-Score](./tutorials/get-the-nutriscore/) +- Dev Journey : [Get the Green-Score](./tutorials/get-the-green-score/) +- Dev Journey : [Get ingredient related analysis on new or existing products (Nova, allergens, additives…)](./tutorials/get-ingredient-related-analysis/) +- Dev Journey : [Adding non-standard fields to a food product using Folksonomy (coming soon for cosmetics, pet food, and other products)](./tutorials/folksonomy-engine/) +- Dev Journey : [Retrieving and adding prices to products using Open Prices](./tutorials/product-prices/) ## Adding more journeys diff --git a/content/docs/Product-Opener/(docs)/api/tutorial-off-api.mdx b/content/docs/Product-Opener/(docs)/api/tutorial-off-api.mdx index f1e9bde..9cc332f 100644 --- a/content/docs/Product-Opener/(docs)/api/tutorial-off-api.mdx +++ b/content/docs/Product-Opener/(docs)/api/tutorial-off-api.mdx @@ -4,7 +4,7 @@ title: "Tutorial on using the Open Food Facts API" Welcome to this tutorial on basic usage of Open Food Facts API. -First, be sure to see our [Introduction to the API](./index.md). +First, be sure to see our [Introduction to the API](./index/). ## Scan A Product To Get Nutri-score @@ -14,7 +14,7 @@ To get a product nutriscore, send a request to the [Get A Product By Barcode](ht ### Authentication -Usually, no authentication is required to query Get A Product Nutri-score. However, there is a basic auth to avoid content indexation in the staging environment (which is used throughout this tutorial). For more details, visit the [Open Food Facts API Environment](index.md#api-deployments). +Usually, no authentication is required to query Get A Product Nutri-score. However, there is a basic auth to avoid content indexation in the staging environment (which is used throughout this tutorial). For more details, visit the [Open Food Facts API Environment](index/#api-deployments). ### Describing the Get Request diff --git a/content/docs/Product-Opener/(docs)/api/tutorial-uploading-photo-to-a-product.mdx b/content/docs/Product-Opener/(docs)/api/tutorial-uploading-photo-to-a-product.mdx index a5207f3..47cf90b 100644 --- a/content/docs/Product-Opener/(docs)/api/tutorial-uploading-photo-to-a-product.mdx +++ b/content/docs/Product-Opener/(docs)/api/tutorial-uploading-photo-to-a-product.mdx @@ -4,7 +4,7 @@ title: "Tutorial on uploading images to the Open Food Facts API" This basic tutorial shows you how to upload an image of a product to the Open Food Facts API. -Be sure to also read the [introduction to the API](./index.md) +Be sure to also read the [introduction to the API](./index/) ## Points to consider before uploading photos @@ -43,7 +43,7 @@ Multilingual products have several photos based on the languages present on the The WRITE operations in the Open Food Facts API require authentication. Therefore you need a valid `user_id`^[user_id_not_email] and `password` to write the photo to 100% Real Orange Juice. > Sign up on the [Open Food Facts App](https://world.openfoodfacts.org/) to get your `user_id` and `password` if you dont have one. -For more details, visit the : [Authentication paragraph in our introduction](../index.md#authentication). +For more details, visit the : [Authentication paragraph in our introduction](../index/#authentication). ^[user_id_not_email]: user_id is the username of your account. You must not use your email address. diff --git a/content/docs/Product-Opener/(docs)/api/tutorials/adding-missing-products.mdx b/content/docs/Product-Opener/(docs)/api/tutorials/adding-missing-products.mdx index 0d455ea..a850719 100644 --- a/content/docs/Product-Opener/(docs)/api/tutorials/adding-missing-products.mdx +++ b/content/docs/Product-Opener/(docs)/api/tutorials/adding-missing-products.mdx @@ -13,13 +13,13 @@ If you have an app that makes POST calls and you don't want your users to authen - `user_id`: myappname - `password`: 123456 -* For a complete reference on AUTH, please read: [Authentication in our introduction](../index.md#authentication) +* For a complete reference on AUTH, please read: [Authentication in our introduction](../index/#authentication) --- ## Adding images to support your edit, and get machine learning predictions If you ask your users just one thing, it would be to send photos of the packaging (front, ingredients, nutrition, recycling, the more the better) -Please refer to our [comprehensive tutorial on uploading images](../tutorial-uploading-photo-to-a-product.md) +Please refer to our [comprehensive tutorial on uploading images](../tutorial-uploading-photo-to-a-product/) --- @@ -101,21 +101,21 @@ It should be structured as: user-agent + user-id. --- ## Leveraging Robotoff ML predictions to simplify life for your users -Leveraging [Robotoff prediction](../intro-robotoff.md) to simplify life for your users. +Leveraging [Robotoff prediction](../intro-robotoff/) to simplify life for your users. You can get a category prediction from images (useful for Nutri-Score and Eco-Score), you can get quality labels prediction, brand predictions, weight predictions from images. You can also get an automatic extraction of ingredients and nutrition facts from an image. To achieve this you need the upload image section above. Adding data like product name, ingredients and nutrition can help, but some predictions can be done with just images. ## Getting your users to check ingredients OCR in an autonomous fashion -Getting your users to [check ingredients OCR in an autonomous fashion](./get-ingredient-related-analysis.md) +Getting your users to [check ingredients OCR in an autonomous fashion](./get-ingredient-related-analysis/) ## Getting your users to input nutrition facts -[Getting your users to input nutrition facts](../../dev/explain-nutrition-data.md) +[Getting your users to input nutrition facts](../../dev/explain-nutrition-data/) ## Getting your users to input packaging data -Getting your users to [input packaging data](../../dev/explain-packaging-data.md) +Getting your users to [input packaging data](../../dev/explain-packaging-data/) ## Showing the result of their work diff --git a/content/docs/Product-Opener/(docs)/api/tutorials/creating-a-local-cache-of-open-food-facts-data.mdx b/content/docs/Product-Opener/(docs)/api/tutorials/creating-a-local-cache-of-open-food-facts-data.mdx index cdcb064..d31413b 100644 --- a/content/docs/Product-Opener/(docs)/api/tutorials/creating-a-local-cache-of-open-food-facts-data.mdx +++ b/content/docs/Product-Opener/(docs)/api/tutorials/creating-a-local-cache-of-open-food-facts-data.mdx @@ -12,7 +12,7 @@ A local cache is a copy of OFF data stored directly on your system or server. Th - **FoodVisor Contributed (Python/MongoDB) backend:** The FoodVisor startup contributed a few years ago a Python-based backend with a MongoDB export, providing a solid starting point for caching in Python environments. - **Project-Specific Caches:** Several OFF projects like open-prices and robotoff have implemented local caches for their own needs. While not immediately reusable, they can serve as valuable references. -- **SDKs** We have [a number of official SDKs](../api.md#sdks) that can be leveraged as part of a caching backend. Please leverage and contribute to those 🙏 +- **SDKs** We have [a number of official SDKs](../api/#sdks) that can be leveraged as part of a caching backend. Please leverage and contribute to those 🙏 - **You can start a project within Open Food Facts to solve this** ### Need for Diverse Solutions @@ -26,7 +26,7 @@ For applications primarily focused on user-generated requests, a local cache may ### Licensing and Data Sharing Even when using a local cache, you're still bound by the Open Database License (ODbL). **Do not mix OFF data with external product data**. All additions or modifications made to OFF data must be shared back to OFF, preferably through the WRITE API. Consider incorporating this functionality into your cache implementation. -For more on legal issues [please read this page](./license-be-on-the-legal-side.md) +For more on legal issues [please read this page](./license-be-on-the-legal-side/) ### Challenges of Cache Maintenance diff --git a/content/docs/Product-Opener/(docs)/api/tutorials/get-ingredient-related-analysis.mdx b/content/docs/Product-Opener/(docs)/api/tutorials/get-ingredient-related-analysis.mdx index dcd09fb..6e6da6d 100644 --- a/content/docs/Product-Opener/(docs)/api/tutorials/get-ingredient-related-analysis.mdx +++ b/content/docs/Product-Opener/(docs)/api/tutorials/get-ingredient-related-analysis.mdx @@ -29,7 +29,7 @@ You can get information about absence or unawareness of the presence of: ## Flow ### The product does not exist -* You can use our [adding products tutorial](./adding-missing-products.md) +* You can use our [adding products tutorial](./adding-missing-products/) ### The product does exist: Get the status of the product and show prompts in case of incomplete ingredients or category (also required for NOVA ultra-processing levels) @@ -54,7 +54,7 @@ then "Add ingredients to see the level of food processing and potential additive * Once the user has entered once of your completion flow, proceed to the next step ### Upload ingredient photo -* [Please follow our dedicated tutorial on photo upload](../tutorial-uploading-photo-to-a-product.md) +* [Please follow our dedicated tutorial on photo upload](../tutorial-uploading-photo-to-a-product/) * The DART SDK is offering support for photo upload, and we encourage you to implement it in one of the official Open Food Facts SDKs if it's not supported yet. * Ensure that your users crop language by language, or take all languages at once, but you perform server side cropping on one specific language before performing the OCR * We're working on a ML solution to detect languages and performing auto-crops per language ([reuse@openfoodfacts.org](mailto:reuse@openfoodfacts.org) to learn more) @@ -68,7 +68,7 @@ then "Add ingredients to see the level of food processing and potential additive #### Selecting photos -* [Please look at the specific tutorial](../tutorial-uploading-photo-to-a-product.md) +* [Please look at the specific tutorial](../tutorial-uploading-photo-to-a-product/) #### Rotating a photo diff --git a/content/docs/Product-Opener/(docs)/api/tutorials/get-the-green-score.mdx b/content/docs/Product-Opener/(docs)/api/tutorials/get-the-green-score.mdx index 4f6daa9..f40e579 100644 --- a/content/docs/Product-Opener/(docs)/api/tutorials/get-the-green-score.mdx +++ b/content/docs/Product-Opener/(docs)/api/tutorials/get-the-green-score.mdx @@ -6,7 +6,7 @@ title: "Helping your users get the Green-Score for any product" - That will then be processed by Open Food Facts to get the computed result you want to show them. - You can implement the complete flow so that they get immediately the result with some effort on their side. - That will ensure user satisfaction -- Please refer to the [product addition tutorial](./adding-missing-products.md) for the technical way to do the required operations (such as category input), and to the high level workflow below for all the cases you have to handle. +- Please refer to the [product addition tutorial](./adding-missing-products/) for the technical way to do the required operations (such as category input), and to the high level workflow below for all the cases you have to handle. ## Table of contents diff --git a/content/docs/Product-Opener/(docs)/api/tutorials/scanning-cosmetics-pet-food-and-other-products.mdx b/content/docs/Product-Opener/(docs)/api/tutorials/scanning-cosmetics-pet-food-and-other-products.mdx index 5e35135..f7940c0 100644 --- a/content/docs/Product-Opener/(docs)/api/tutorials/scanning-cosmetics-pet-food-and-other-products.mdx +++ b/content/docs/Product-Opener/(docs)/api/tutorials/scanning-cosmetics-pet-food-and-other-products.mdx @@ -29,7 +29,7 @@ title: "Open Beauty Facts, Open Pet Food Facts, Open Products Facts experimental - No nutrition table - No Green-Score, Nutri-Score or NOVA groups for ultra-processing -- Most data will be modelled using the [Folksonomy Engine](docs/api/tutorials/folksonomy-engine.md) +- Most data will be modelled using the [Folksonomy Engine](docs/api/tutorials/folksonomy-engine/) ### Important APIs if you want to scan any kind of product (or help your users avoid adding cosmetics by mistake in Open Food Facts) diff --git a/content/docs/Product-Opener/(docs)/dev/explain-pro-dev-setup.mdx b/content/docs/Product-Opener/(docs)/dev/explain-pro-dev-setup.mdx index 425c1f8..3262759 100644 --- a/content/docs/Product-Opener/(docs)/dev/explain-pro-dev-setup.mdx +++ b/content/docs/Product-Opener/(docs)/dev/explain-pro-dev-setup.mdx @@ -3,7 +3,7 @@ title: "Explanation on Docker Setup of pro platform for development" --- This explains how we setup docker file for pro platform development. -For explanations on how to use it, see: [how-to-guides/pro-development](how-to-develop-producer-platform.md) +For explanations on how to use it, see: [how-to-guides/pro-development](how-to-develop-producer-platform/) off is the public facing application (world.openfoodfacts.org) off-pro is the producers platform (world.pro.openfoodfacts.org) @@ -13,7 +13,7 @@ When we work on the pro platform for development we want: * off-pro containers to talk to each other, and, generally, have their own volumes * off and off-pro containers to talk to shared containers (from openfoodfacts-authentication and openfoodfacts-shared-services), - see [dependencies](https://github.com/openfoodfacts/.github/blob/main/docs/service-dependencies.md) + see [dependencies](https://github.com/openfoodfacts/.github/blob/main/docs/service-dependencies/) * minion and backend from both apps to access the same postgres database (which stores tasks queues) * off and off-pro backends / minion needs to share some volumes: diff --git a/content/docs/Product-Opener/(docs)/dev/explain-user-management.mdx b/content/docs/Product-Opener/(docs)/dev/explain-user-management.mdx index b82781c..ebd002e 100644 --- a/content/docs/Product-Opener/(docs)/dev/explain-user-management.mdx +++ b/content/docs/Product-Opener/(docs)/dev/explain-user-management.mdx @@ -104,7 +104,7 @@ is part of the organization information, stored in a file on disk (`orgs` datase ## In development In development, the openfoodfacts-auth project is a service dependency of this project. -See [Service Dependencies](https://github.com/openfoodfacts/.github/blob/main/docs/service-dependencies.md) +See [Service Dependencies](https://github.com/openfoodfacts/.github/blob/main/docs/service-dependencies/) If you want to become admin of the website, you just need to create a user using one of the account listed in `admins`, diff --git a/content/docs/Product-Opener/(docs)/dev/how-to-develop-producer-platform.mdx b/content/docs/Product-Opener/(docs)/dev/how-to-develop-producer-platform.mdx index 7267d32..573be93 100644 --- a/content/docs/Product-Opener/(docs)/dev/how-to-develop-producer-platform.mdx +++ b/content/docs/Product-Opener/(docs)/dev/how-to-develop-producer-platform.mdx @@ -6,7 +6,7 @@ Here is how to develop for the producers platform using docker. ### Prerequisites: -- Docker should already be [set up for development](how-to-quick-start-guide.md). +- Docker should already be [set up for development](how-to-quick-start-guide/). ### Shell Setup: You will need two types of shells: @@ -35,9 +35,9 @@ If you need to work on product import/export or interact with the public platfor - in your *non pro shell*, run a `docker compose up frontend` Now, the public database can be accessed at `openfoodfacts.localhost`.If you need to access the *pro* HTTP server, reverse these steps. -Note that if you [use direnv](how-to-use-direnv.md), the setup should work seamlessly without redefining the variables set by `setenv.sh`. +Note that if you [use direnv](how-to-use-direnv/), the setup should work seamlessly without redefining the variables set by `setenv.sh`. -An explanation of the setup can be found at [explain-pro-dev-setup.md](explain-pro-dev-setup.md) +An explanation of the setup can be found at [explain-pro-dev-setup.md](explain-pro-dev-setup/) - If you want to see the state of tasks, you can run: diff --git a/content/docs/Product-Opener/(docs)/dev/how-to-develop-using-docker.mdx b/content/docs/Product-Opener/(docs)/dev/how-to-develop-using-docker.mdx index 8e25805..7daba2d 100644 --- a/content/docs/Product-Opener/(docs)/dev/how-to-develop-using-docker.mdx +++ b/content/docs/Product-Opener/(docs)/dev/how-to-develop-using-docker.mdx @@ -4,7 +4,7 @@ title: "How to use Docker to Develop - a guide" This guide is for developers and newcomers to help them debug and explore Docker. -This page describes how to test and debug your changes once you have set up the project, Product Opener with Docker using [dev environment quick start guide](how-to-quick-start-guide.md). +This page describes how to test and debug your changes once you have set up the project, Product Opener with Docker using [dev environment quick start guide](how-to-quick-start-guide/). ## Checking logs @@ -231,7 +231,7 @@ then you can use whatever docker compose command. **Note:** This terminal will remain in `pro` mode until you end its session. -See also [Developing on the producers platform](how-to-develop-producer-platform.md) +See also [Developing on the producers platform](how-to-develop-producer-platform/) ### different .env file diff --git a/content/docs/Product-Opener/(docs)/dev/how-to-quick-start-guide.mdx b/content/docs/Product-Opener/(docs)/dev/how-to-quick-start-guide.mdx index 414009f..79e23d4 100644 --- a/content/docs/Product-Opener/(docs)/dev/how-to-quick-start-guide.mdx +++ b/content/docs/Product-Opener/(docs)/dev/how-to-quick-start-guide.mdx @@ -3,7 +3,7 @@ title: "How to setup the Dev environment (quick start guide)" --- This guide will allow you to rapidly build a ready-to-use development environment for **Product Opener** running in Docker. -As an alternative to setting up your environment locally, follow the [Gitpod how-to guide](how-to-use-gitpod.md) +As an alternative to setting up your environment locally, follow the [Gitpod how-to guide](how-to-use-gitpod/) to instantly provision a ready-to-code development environment in the cloud. First setup time estimate is `~10min` with the following specs: @@ -17,7 +17,7 @@ First setup time estimate is `~10min` with the following specs: Docker provides an isolated environment, very close to a Virtual Machine. This environment contains everything required to launch the Open Food Facts server. There is **no need to install** Perl, Perl modules, Nginx, or Apache separately. -> **_NOTE:_** New to Perl? Check [how to learn perl](how-to-learn-perl.md)! +> **_NOTE:_** New to Perl? Check [how to learn perl](how-to-learn-perl/)! **Installation steps:** - GIT version >= 2.25.0 @@ -239,7 +239,7 @@ The `.env` file also contains some useful Docker Compose variables: Instead of modifying `.env` (and risk committing it inadvertently), you can also set needed variables in your shell; they will override `.env` values. Consider creating a `.envrc` file that you source each time you need to work on the project. -On linux and macOS, you can automatically do it if you [use direnv](how-to-use-direnv.md). +On linux and macOS, you can automatically do it if you [use direnv](how-to-use-direnv/). ## 3. Build your dev environment @@ -291,7 +291,7 @@ The command will run 2 subcommands: * You might not immediately see the test products: create an account, login, and they should appear. -* For a full description of available make targets, see [Docker / Makefile commands](ref-docker-commands.md) +* For a full description of available make targets, see [Docker / Makefile commands](ref-docker-commands/) **Hosts file:** @@ -305,13 +305,13 @@ Since the default `PRODUCT_OPENER_DOMAIN` in the `.env` file is set to `openfood ### Going further -To learn more about developing with Docker, see the [Docker developer's guide](how-to-develop-using-docker.md). +To learn more about developing with Docker, see the [Docker developer's guide](how-to-develop-using-docker/). -To have all site pages on your dev instance, see [Using pages from openfoodfacts-web](how-to-use-pages-from-openfoodfacts-web.md) +To have all site pages on your dev instance, see [Using pages from openfoodfacts-web](how-to-use-pages-from-openfoodfacts-web/) -[Using Repl](how-to-use-repl.md) offers you a way to play with perl. +[Using Repl](how-to-use-repl/) offers you a way to play with perl. -Specific notes are provided on [applying AGRIBALYSE updates to support the Ecoscore](how-to-update-agribalyse-ecoscore.md) calculation. +Specific notes are provided on [applying AGRIBALYSE updates to support the Ecoscore](how-to-update-agribalyse-ecoscore/) calculation. ## Visual Studio Code @@ -474,7 +474,7 @@ Then, execute this: docker compose up ``` > **Note:** -> To know more about docker compose commands do read [this guide](how-to-develop-using-docker.md) +> To know more about docker compose commands do read [this guide](how-to-develop-using-docker/) ### make dev error: [build_lang] Error 13 - can't write into /mnt/podata/data/Lang.openfoodfacts.localhost.sto diff --git a/content/docs/Product-Opener/(docs)/dev/how-to-use-gitpod.mdx b/content/docs/Product-Opener/(docs)/dev/how-to-use-gitpod.mdx index def8f5f..cf5709b 100644 --- a/content/docs/Product-Opener/(docs)/dev/how-to-use-gitpod.mdx +++ b/content/docs/Product-Opener/(docs)/dev/how-to-use-gitpod.mdx @@ -15,8 +15,8 @@ Note that while this how-to is tailored for Gitpod, using alternatives like [Git similar. For the most part, development on Gitpod is similar to developing locally as documented -in the [quickstart guide](how-to-quick-start-guide.md) -and [docker-developer-guide](how-to-develop-using-docker.md); however accessing your dev-deployment of +in the [quickstart guide](how-to-quick-start-guide/) +and [docker-developer-guide](how-to-develop-using-docker/); however accessing your dev-deployment of `openfoodfacts-server` requires an extra step. ## Connect GitHub and Gitpod @@ -36,7 +36,7 @@ On the Gitpod side, you can also update what Gitpod is allowed to do with your G Once the repository is open in Gitpod, other instructions in the -[quick-start guide](how-to-quick-start-guide.md) can be generally followed. +[quick-start guide](how-to-quick-start-guide/) can be generally followed. ## Accessing your development instance of openfoodfacts-server @@ -63,7 +63,7 @@ on http://openfoodfacts.localhost just as documented in the quickstart guide! **Remark:** on MacOS or Linux, when trying to bind, you might see a bind fail. Remember that any port below 1024 is reserved for the root user. * The easiest fix is to add `sudo` just before the ssh command. -* Another way is to switch to port 8080: in gitpod, open the .env file (or better [user direnv](./how-to-use-direnv.md)) and change PRODUCT_OPENER_PORT=80 by PRODUCT_OPENER_PORT=8080, then replace `-L 80:localhost:80` by `-L 8080:localhost:8080` in the ssh command and connect to world.openfoodfacts.localhost:8080. **Rollback the changes on .env before making a pull request!** +* Another way is to switch to port 8080: in gitpod, open the .env file (or better [user direnv](./how-to-use-direnv/)) and change PRODUCT_OPENER_PORT=80 by PRODUCT_OPENER_PORT=8080, then replace `-L 80:localhost:80` by `-L 8080:localhost:8080` in the ssh command and connect to world.openfoodfacts.localhost:8080. **Rollback the changes on .env before making a pull request!** **Remark:** the address to connect with ssh can change after a few days. If you get a ```Connection closed by ... port 22``` simply go back to https://gitpod.io/workspaces and copy the new address. diff --git a/content/docs/Product-Opener/(docs)/dev/how-to-use-repl.mdx b/content/docs/Product-Opener/(docs)/dev/how-to-use-repl.mdx index dc0b5c2..6aa261c 100644 --- a/content/docs/Product-Opener/(docs)/dev/how-to-use-repl.mdx +++ b/content/docs/Product-Opener/(docs)/dev/how-to-use-repl.mdx @@ -2,7 +2,7 @@ title: "How to use Perl REPL (re.pl)" --- -> **_NOTE:_** New to Perl? Check [how to learn perl](how-to-learn-perl.md)! +> **_NOTE:_** New to Perl? Check [how to learn perl](how-to-learn-perl/)! On your local dev instance, the "backend" container comes with [Devel::REPL](https://metacpan.org/pod/Devel::REPL) installed. diff --git a/content/docs/Product-Opener/(docs)/dev/how-to-use-vscode.mdx b/content/docs/Product-Opener/(docs)/dev/how-to-use-vscode.mdx index 0e54418..ca74c4f 100644 --- a/content/docs/Product-Opener/(docs)/dev/how-to-use-vscode.mdx +++ b/content/docs/Product-Opener/(docs)/dev/how-to-use-vscode.mdx @@ -18,7 +18,7 @@ One way to have perlcritic work is the following: . .envrc >/dev/null 2>&1 docker compose run --rm --no-deps backend perlcritic "$@" 2>/dev/null ``` - the second line is useful only if you [use direnv](how-to-use-direnv.md) + the second line is useful only if you [use direnv](how-to-use-direnv/) * `chmod +x perlcritic.sh` * patch perlcritic by editing its files, following [sfodje/perlcritic issue #26](https://github.com/sfodje/perlcritic/issues/26#issuecomment-1006411268) * edit the perlcritic configuration in workspace to set the value (after adjusting the pathname for your own OFF setup): @@ -41,7 +41,7 @@ The extension [Language Server and Debugger](https://marketplace.visualstudio.co >&2 echo "launching $COMMAND" docker compose run --rm --no-deps -T -p 127.0.0. 1:13603:13603 backend $COMMAND ``` - Note: the second line is useful only if you [use direnv](how-to-use-direnv.md) + Note: the second line is useful only if you [use direnv](how-to-use-direnv/) * `chmod +x shell-into-appserver.sh` * Edit workspace settings to have those settings: ```json diff --git a/content/docs/Product-Opener/(docs)/dev/how-to-write-and-run-tests.mdx b/content/docs/Product-Opener/(docs)/dev/how-to-write-and-run-tests.mdx index 54a3a22..7f49217 100644 --- a/content/docs/Product-Opener/(docs)/dev/how-to-write-and-run-tests.mdx +++ b/content/docs/Product-Opener/(docs)/dev/how-to-write-and-run-tests.mdx @@ -106,7 +106,7 @@ If you regenerate test results, be sure to check carefully that the changes in y ### Github action helper You can trigger an update of tests results using a special comment on your PR. -See [How to use automated PR actions - updating tests-results](./how-to-use-automated-pr-actions.md#updating-tests-results) +See [How to use automated PR actions - updating tests-results](./how-to-use-automated-pr-actions/#updating-tests-results) ## Debugging with tests diff --git a/content/docs/Product-Opener/(docs)/dev/index.mdx b/content/docs/Product-Opener/(docs)/dev/index.mdx index 54bb10f..aef821b 100644 --- a/content/docs/Product-Opener/(docs)/dev/index.mdx +++ b/content/docs/Product-Opener/(docs)/dev/index.mdx @@ -4,15 +4,15 @@ title: "Introduction to Product Opener developer documentation" This documentation is for developers who wants to understand technical aspects of Product Opener. -To use the API, see [API Documentation](../api/index.md) +To use the API, see [API Documentation](../api/index/) The repository for the project is at https://github.com/openfoodfacts/openfoodfacts-server/ Some documentation to get you started: -* [Quick start guide (Docker)](how-to-quick-start-guide.md) -* [Developer guide (Docker)](how-to-develop-using-docker.md) -* [Developer guide (Gitpod)](how-to-use-gitpod.md) +* [Quick start guide (Docker)](how-to-quick-start-guide/) +* [Developer guide (Docker)](how-to-develop-using-docker/) +* [Developer guide (Gitpod)](how-to-use-gitpod/) Note: documentation follows the [Diátaxis Framework](https://diataxis.fr/) diff --git a/content/docs/Product-Opener/(docs)/dev/ref-docker-commands.mdx b/content/docs/Product-Opener/(docs)/dev/ref-docker-commands.mdx index a5fc3f4..a2ec4af 100644 --- a/content/docs/Product-Opener/(docs)/dev/ref-docker-commands.mdx +++ b/content/docs/Product-Opener/(docs)/dev/ref-docker-commands.mdx @@ -6,4 +6,4 @@ title: "Reference Docker / Makefile commands" DO NOT MODIFY this file it is overwritten by the docker/README file at compile time --> */} -See [README in `docker` folder](../../docker/README.md) +See [README in `docker` folder](../../docker/README/) diff --git a/content/docs/Product-Opener/(docs)/dev/ref-perl.mdx b/content/docs/Product-Opener/(docs)/dev/ref-perl.mdx index e8fc7bf..e39540a 100644 --- a/content/docs/Product-Opener/(docs)/dev/ref-perl.mdx +++ b/content/docs/Product-Opener/(docs)/dev/ref-perl.mdx @@ -5,4 +5,4 @@ title: "Reference Perl code documentation" The documentation in Plain Old Format (aka POD) for perl module is compiled from in file documentation. -[See the Perl reference documentation](ref-perl-pod.md) \ No newline at end of file +[See the Perl reference documentation](ref-perl-pod/) \ No newline at end of file diff --git a/content/docs/Product-Opener/(docs)/index.mdx b/content/docs/Product-Opener/(docs)/index.mdx index d0bbc64..1da1816 100644 --- a/content/docs/Product-Opener/(docs)/index.mdx +++ b/content/docs/Product-Opener/(docs)/index.mdx @@ -6,9 +6,9 @@ Welcome to the documentation of **Product Opener**, the web server at the heart It also powers the sibling **Open \[[Beauty](https://world.openbeautyfacts.org/)|[Pet Food](https://world.openpetfoodfacts.org/)|[Products](https://world.openproductsfacts.org/)\] Facts** projects -* If you want to use the API or are interested in the data, look at [API documentation](api/index.md) and [Events documentation](./events/README.md) +* If you want to use the API or are interested in the data, look at [API documentation](api/index/) and [Events documentation](./events/README/) -* If you are a developer, look at [Developer documentation](dev/index.md) +* If you are a developer, look at [Developer documentation](dev/index/) The repository for the project is at https://github.com/openfoodfacts/openfoodfacts-server/ diff --git a/scripts/generate-docs.mjs b/scripts/generate-docs.mjs index 37e0570..0c3c4a3 100644 --- a/scripts/generate-docs.mjs +++ b/scripts/generate-docs.mjs @@ -162,3 +162,14 @@ if (existsSync('./specfiles-json/nutripatrol-openapi.json')) { } else { console.log('Nutripatrol spec not found, skipping Nutripatrol documentation generation'); } + +// Fix malformed code blocks +// The Fumadocs .md to .mdx transpiler adds titles but without adding a language +// which then makes Shiki fail, so we add 'text' as the language when there isn't one +execSync("find content/docs -name '*.mdx' -exec sed -i 's/^``` \\+\\(\\w\\+=.\\+\\)$/```text \\1/' {} \\;", { stdio: 'inherit' }); + +// Fix internal links +// Change internal links from .md extension to directory format for the docs site +// e.g., /docs/Product-Opener/dev/how-to-develop-using-docker.md -> /docs/Product-Opener/dev/how-to-develop-using-docker/ +// Works with any link ending in .md that doesn't contain :// (excludes http/https) +execSync("find content/docs -name '*.mdx' -exec sed -i '/:\\/\\/\\//! s|\\([^)]*\\)\\.md|\\1/|g' {} \\;", { stdio: 'inherit' });