{"id":16931543,"url":"https://github.com/avdata99/collab-test-03","last_synced_at":"2026-05-18T03:34:38.936Z","repository":{"id":72337759,"uuid":"584849732","full_name":"avdata99/collab-test-03","owner":"avdata99","description":null,"archived":false,"fork":false,"pushed_at":"2023-01-03T18:17:24.000Z","size":892,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-22T00:54:57.782Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/avdata99.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-01-03T17:12:40.000Z","updated_at":"2023-01-03T17:12:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"f0ef54d6-bad1-4cd4-91f4-a36bd59eb15e","html_url":"https://github.com/avdata99/collab-test-03","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"okfn/okfn-collaborative-docs","purl":"pkg:github/avdata99/collab-test-03","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdata99%2Fcollab-test-03","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdata99%2Fcollab-test-03/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdata99%2Fcollab-test-03/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdata99%2Fcollab-test-03/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avdata99","download_url":"https://codeload.github.com/avdata99/collab-test-03/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdata99%2Fcollab-test-03/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33163765,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"online","status_checked_at":"2026-05-18T02:00:06.436Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-10-13T20:44:13.773Z","updated_at":"2026-05-18T03:34:38.930Z","avatar_url":"https://github.com/avdata99.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Publish docs via GitHub Pages](https://github.com/okfn/okfn-collaborative-docs/actions/workflows/page.yml/badge.svg)](https://github.com/okfn/okfn-collaborative-docs/actions/workflows/page.yml)\n[![Tests](https://github.com/okfn/okfn-collaborative-docs/actions/workflows/tests.yml/badge.svg)](https://github.com/okfn/okfn-collaborative-docs/actions/workflows/tests.yml)\n\n# OKFN Collaborative Documentation tool\n\nThis is a GitHub template to create multilanguage collaborative documentation with a\npublic html site and a PDF version. It's based on [mkdocs](https://www.mkdocs.org).   \n\n## Creating my first documentation\n\nAt this [repo url](https://github.com/okfn/okfn-collaborative-docs/)\nclick on the _Use this template_ + _Create new repository_ button\nor go directly to the [generate from template url](https://github.com/okfn/okfn-collaborative-docs/generate)\n\n![Use template](docs/imgs/use-template.png)\n\nDo not forget to define your new repository as **Public**.  \n\n### Prepare your local environment.\n\nClone your new pository and install the project requirements.\nThis is an example for Linux/Ubuntu:\n\n```bash\n# Clone your new repository \ngit clone git@github.com:YOUR-ORG/YOUR-REPO-NAME.git\n# Create a Python3 virtual environment\npython3 -m venv /path/to/new/virtual/environment\n# Activate the virtual environment\nsource /path/to/new/virtual/environment/bin/activate\n# Install the project requirements\ncd YOUR-REPO-NAME\npip install -r requirements.txt\n``` \n\n### Define your custom settings\n\nYour main configuration file is `/conf/custom.yml`.  \n\n#### Languages\n\nFirst of all, you need to define your site name and the languages you want to use.  \nDefine languages at `custom_extra`-\u003e`alternate` and the site name at `site_name`.  \n\n```yaml\ncustom_extra:\n  # define all available languages\n  alternate:\n    - name: English\n      lang: en\n    - name: Español\n      lang: es\n```\n\n```yaml\nsite_name:\n    en: My site name\n    es: Mi sitio\n```\n\nYou can add as many languages as you want. \nAll languages will be required for other multilanguage configurations.  \n\n#### URL settings\n\nNow, define your GitHub (required) settings.\n\n```yaml\nrepo_user: your-github-user-or-org-name\nrepo_name: you-new-repo-name\n```\n_Note:_ `repo_user` and `repo_name` came from your new GitHub repository url: https://github.com/REPO_USER/REPO_NAME\n\nIf you plan to use the default GitHub domain, you are done with this settings.  \nThe site will be available at https://USER.github.io/YOU-REPO-NAME.  \nConversely, if you plan to use a custom domain, you'll need something like this:\n\n```yaml\n# Only for custom domains you can use:\ncustom_site_url: https://your-site.org\n# public_url_base_path: /some-base-path-folder (only if required)\n```\n_Note:_ You'll need a CNAME record pointing to `USER.github.io`\n\n#### Other settings\n\nThe `site_description`, `copyright` and `site_author` are self-explanatory.  \n\nIf you need to define custom context values to use in your templates, you can do it with the `custom_extra` setting.  \n\nSome examples:\n\n```yaml\ncustom_extra:\n\n  # other custom extras (like alternate for )...\n  # define custom context values\n\n  my_value: Some text (will be available for all .md and .html files as {{ my_value }})\n  my_dict:\n    some_key: \"my custom value in english\" (will be available for all .md and .html files as {{ my_dict.some_key }})\n    some_key2: \"mi valor personalizado en español\"\n  my_list:\n    # available to iterate with {% for item in my_list %} {{ item }} {% endfor %}\n    - \"my custom value in english\" (will be available for all .md and .html files as {{ my_list.0 }})\n    - \"mi valor personalizado en español\"\n  my_list_of_dicts:\n    # available to iterate with {% for k, v in my_list_of_dicts %} {{ k }}: {{ v }} {% endfor %}\n    - some_key: \"my custom value in english\"\n    - some_key2: \"mi valor personalizado en español\"\n```\n\n### Define the site structure\n\nThe `nav` setting is the main configuration for the site structure.  \nYou need to add a sub-section for each language (`nav-en`, `nav-es`, etc).  \n\nInside the `page/docs` folder you need to create (if not exists) a folder\nfor each language (`docs-en`, `docs-es`, etc).  \nFor all languages, an `index.md` file is required.  \n\nInside each language folder you need to create (if not exists) the same\nfiles described in the `nav-LANG` setting.  \n\n### Custom site styles and javascript\n\nIf you need custom CSS styles, you can add them to the `page/assets/css/custom.css` file.  \nIf you need custom javascript, you can add them to the `page/assets/js/app.js` file.  \n\n### Other static resources\n\nIf you need other static resources (like images), you can add them to the `page/assets` folder and they will be availabe\nat `{{ assets_folder }}` in your template/markdown files (they are several examples available in the test templates).  \n\nFor example `\u003cimg src=\"{{ assets_folder }}/img/cordoba-rio.jpg\"/\u003e` or\n`![cba river]({{ assets_folder }}/img/cordoba-rio.jpg)`.  \n\n### Prepare your site\n\nPrepare your internal custom settings for each language and prepare the environment\n\n```bash\npython3 okf_collab_docs/run.py build-config\n```\n\nFor a list of common errors building your site, see [here](docs/build-errors.md).  \n\nThis process will create files and folders:\n - All the `conf/mkdocs-LANG.yml` required files (you don't need to touch them)\n - All the `page/docs/fixed-docs-LANG` required folder with an updated version of your MD files\n - Copy all assets to the `site` folder.\n\nYou don't need to touch any of this resources. They are _.gitignored_ and will be used to build the site.  \n\nIf this process succeeds, then **you're ready to deploy your site to GitHub Pages**, simply push your changes to GitHub.  \nYou can check the build process at the _Actions_ tab (https://github.com/USER/REPO-NAME/actions).  \nOnce the GitHub action finished, you'll need to enable github pages at https://github.com/USER/REPO-NAME/settings/page\nand select the `gh-pages` branch.  \n\n![gh pages](/docs/imgs/gh-pages.png)\n\nAfter some minutes (GitHub will process your static site), your site will be available at https://USER.github.io/REPO-NAME  \n\n#### Build your local site\n\nYou can also test you site locally and skip waiting for each GitHub action to finish.  \nYou can do this by builing the site locally and serving it with a local server.  \n\n```\npython3 okf_collab_docs/run.py build-local-site\n```\n\n... and serve the site locally\n\n```\npython3 okf_collab_docs/run.py serve\n```\n\nYou'll see `serving at http://localhost:8033` and your local site is now redy to test with\nall the languages you defined.  \n**Note**: If you have a `Port in use` error, you can call\n`python3 okf_collab_docs/run.py serve -p 8034` to use a different port.  \n\n### PDF version\n\nA PDF version for each language is generated automatically and it will be available at:\n - English version: `/pdf/doc-en.pdf`\n - Other languages: `/LANG/pdf/doc-LANG.pdf`\n\nThe URL for the PDF version is available in the `{{ pdf_url }}` variable in the template files.  \nA _nav_ link pointing this URL will be added automatically at the end of each language site menu.  \n\nThe `/page/pdf/pdf-template-LANG` folder include custom styles,\ncover and back cover templates for each language.  \n[If you know what you're doing](https://github.com/orzih/mkdocs-with-pdf/blob/master/README.md#sample-pdf_event_hookpy-or-pdf_event_hook__init__py),\nyou can modify the `/pdf_event_hook.py` file.  \n\n## More docs\n\nMore info about this project:\n\n - General notes: [docs/general-notes.md](docs/general-notes.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favdata99%2Fcollab-test-03","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favdata99%2Fcollab-test-03","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favdata99%2Fcollab-test-03/lists"}