{"id":22018391,"url":"https://github.com/flavienbwk/freshdoc","last_synced_at":"2026-04-29T08:04:18.282Z","repository":{"id":165265940,"uuid":"640070150","full_name":"flavienbwk/freshdoc","owner":"flavienbwk","description":"Keep code and text snippets in sync across your git repos.","archived":false,"fork":false,"pushed_at":"2023-07-15T10:33:56.000Z","size":501,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-28T16:17:21.358Z","etag":null,"topics":["ci","documentation","gitops","sdlc"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flavienbwk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-12T23:01:45.000Z","updated_at":"2023-05-21T12:20:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"af4aea62-2d08-4c5c-81da-47e09d2955e2","html_url":"https://github.com/flavienbwk/freshdoc","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavienbwk%2Ffreshdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavienbwk%2Ffreshdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavienbwk%2Ffreshdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavienbwk%2Ffreshdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flavienbwk","download_url":"https://codeload.github.com/flavienbwk/freshdoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245081782,"owners_count":20557843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","documentation","gitops","sdlc"],"created_at":"2024-11-30T05:12:04.425Z","updated_at":"2026-04-29T08:04:13.261Z","avatar_url":"https://github.com/flavienbwk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Freshdoc\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./logo.png\" width=\"196px\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/flavienbwk/freshdoc/actions/workflows/build-dev.yaml\"\u003e\n        \u003cimg src=\"https://github.com/flavienbwk/freshdoc/actions/workflows/build-dev.yaml/badge.svg\" alt=\"Dev build\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/flavienbwk/freshdoc/actions/workflows/build-prod.yaml\"\u003e\n        \u003cimg src=\"https://github.com/flavienbwk/freshdoc/actions/workflows/build-prod.yaml/badge.svg\" alt=\"Prod build\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pepy.tech/badge/black\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Using black Python formatter\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"./LICENSE\"\u003e\n        \u003cimg src=\"https://black.readthedocs.io/en/stable/_static/license.svg\" alt=\"License: MIT\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nKeep code and text snippets in sync across your git repos.\n\nUseful to track any evolving info stored in your documentations, such as **team members' names**, **phone numbers**, **e-mail addresses** or **server IPs** across your repos.\n\n## Features\n\n- Check for non-identical text snippets accross repos\n- Detect dead links\n- Integrates with any git repo\n- Callable through [curl](https://curl.se/)\n\n## Usage\n\n### Declare a reference\n\nWrap text or code to be tracked in a markdown comment including a Freshdoc reference tag.\n\n```markdown\n# My incredible documentation\n\n## Support\n\nCurrent team includes :\n\u003c!-- \u003cfd:customer_support_team:1\u003e --\u003e\n- Juliet CAPULET\n- Antigone THEBAN\n- Jean VALJEAN\n\u003c!-- \u003c/fd:customer_support_team:1\u003e --\u003e\n\nPhone number : \u003c!-- \u003cfd:phone_cs:1\u003e --\u003e+33900000001\u003c!-- \u003c/fd:phone_cs:1\u003e --\u003e\n\n```\n\n### Validate in GitLab CI\n\nUse it with _curl_ :\n\n```yaml\nstages:\n    - test\n\nfreshdoc:\n    stage: test\n    script:\n        - apk update \u0026\u0026 apk add bash curl jq\n        - |\n            #!/bin/bash\n            response=(curl --request POST \\\n            --max-time 30 -s -w \"\\n%{http_code}\" \\\n            -H \"Content-Type=application/x-www-form-urlencoded\" \\\n            -d \"repos_to_check=https://gitlab-ci-token:${CI_JOB_TOKEN}@mygitlab.com/${CI_PROJECT_PATH_SLUG},https://gitlab-ci-token:${CI_JOB_TOKEN}@mygitlab.com/group2/project2\" \\\n            -d \"branches_to_check=main,master,develop,${CI_COMMIT_BRANCH}\" \\\n            -d \"ssl_verify=true\" \\\n            -d \"file_extensions=md,txt\" \\\n            -d \"excluded_directories=node_modules/**\" \\\n            -d \"check_dead_links=true\" \\\n            -d \"verbose=false\" \\\n            http://localhost:8080/check)\n            http_code=$(echo \"$response\" | tail -n 1)\n            payload=$(echo \"$response\" | head -n -1)\n            echo \"$payload\" | jq -r\n            if [ \"$response_code\" != \"200\" ]; then\n                echo \"Freshdoc returned a non-200 HTTP code : check the logs above.\"\n                exit 1\n            fi\n```\n\n- A `200` HTTP code will be returned if no problem was encountered, otherwise `400`.\n- Body with eventually include a detailed list of problems to solve.\n\n| Parameter                                                                                                          | Value description                                                                                                                                                                  |\n| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **repos_to_check**                                                                                                 | Required. Commas-delimited list of repo URLs to track references. Optionally include credentials with this format : _https://{username}:{password}@mygitserver.com/group/project_. |\n| **branches_to_check**                                                                                              | Default: \"main,master,develop\". Commas-delimited list of branches to track. Unexistant branches will be skipped.                                                                   |\n| [**ssl_verify**](https://stackoverflow.com/questions/11621768/how-can-i-make-git-accept-a-self-signed-certificate) | \"true\" (default) or \"false\". Enable or disable git clone command's SSL verification for provided repos.                                                                            |\n| **file_extensions**                                                                                                | Default: \"md,txt\". Commas-delimited list of file extensions in which Freshdoc will check for references.                                                                           |\n| **excluded_directories**                                                                                           | No default value. Commas-delimited list of glob patterns indicating which directory to ignore for all provided repos.                                                              |\n| **check_dead_links**                                                                                               | \"true\" (default) or \"false\". Checks if links are valid (responsive and HTTP code between 200 and 403). Only checks the first repo from the REPOS_TO_CHECK list.                    |\n| **verbose**                                                                                                        | \"true\" or \"false\" (default). Returns analysis details in response. Useful for debugging.                                                                                           |\n\n## Start server\n\nUsing Docker and docker-compose :\n\n```bash\ndocker-compose -f prod.docker-compose.yml up --build -d\n```\n\nAPI will be available on port `8080` by default.\n\n## Syntax\n\nThe Freshdoc tag is composed of 3 items. Let's take an example :\n\n```markdown\n\u003c!-- \u003cfd:ref_name:1\u003e --\u003e\ntext\n\u003c!-- \u003c/fd:ref_name:1\u003e --\u003e\n```\n\n- `fd` is for identifying a Freshdoc tag in a file\n- `ref_name` is a small name to identify the snippet to track\n- `1` is the version of your snippet to make it upgradable\n\n\u003e `\u003c!-- --\u003e` are optional. Freshdoc is matching any tag found under the `\u003cfd:ref_name:1\u003e\u003c/fd:ref_name:1\u003e` format in the content of a file.\n\n## Upgrading a reference\n\nLet's say you have two repos A and B to keep in sync. To upgrade a reference, increase its version number in repo A, commit and push.\n\nNow-on, any push in repo B will trigger a warning until the **value** and **version** of the reference are matching.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflavienbwk%2Ffreshdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflavienbwk%2Ffreshdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflavienbwk%2Ffreshdoc/lists"}