{"id":22544327,"url":"https://github.com/sator-imaging/docfx-pages","last_synced_at":"2025-04-09T23:50:49.000Z","repository":{"id":213029564,"uuid":"732838628","full_name":"sator-imaging/docfx-pages","owner":"sator-imaging","description":"Deploy docfx API Reference to GitHub Pages only 1 Action","archived":false,"fork":false,"pushed_at":"2025-03-17T04:08:27.000Z","size":794,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T23:50:41.333Z","etag":null,"topics":["csharp","docfx","documentation","github","github-actions","github-pages","unity","unity3d"],"latest_commit_sha":null,"homepage":"https://sator-imaging.github.io/docfx-pages/","language":"C#","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/sator-imaging.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},"funding":{"github":["sator-imaging"]}},"created_at":"2023-12-18T01:06:40.000Z","updated_at":"2025-03-17T03:57:02.000Z","dependencies_parsed_at":"2023-12-24T03:18:26.641Z","dependency_job_id":"fcd6b581-0ac3-41cf-a0fd-2eb43ea60872","html_url":"https://github.com/sator-imaging/docfx-pages","commit_stats":null,"previous_names":["sator-imaging/docfx-pages"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sator-imaging%2Fdocfx-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sator-imaging%2Fdocfx-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sator-imaging%2Fdocfx-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sator-imaging%2Fdocfx-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sator-imaging","download_url":"https://codeload.github.com/sator-imaging/docfx-pages/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131455,"owners_count":21052819,"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":["csharp","docfx","documentation","github","github-actions","github-pages","unity","unity3d"],"created_at":"2024-12-07T14:06:57.628Z","updated_at":"2025-04-09T23:50:48.985Z","avatar_url":"https://github.com/sator-imaging.png","language":"C#","funding_links":["https://github.com/sponsors/sator-imaging"],"categories":[],"sub_categories":[],"readme":"# `docfx` for GitHub Pages\r\n\r\nDeploy beautiful API reference to GitHub Pages with only 1 action. No unnecessary file upload and complicated `docfx` setup.\r\n\r\n- ✅ No `.json`, `.yml` and `.csproj` Files Required\r\n- ✅ Automatic HeaderDoc \u0026 TOC Generator\r\n- ✅ Unity Project \u0026 Editor Extension Supported\r\n\r\n\r\n| Light Theme | Dark Theme |\r\n|:-----------:|:----------:|\r\n| ![Light Theme](images/docfx-pages-light.png)  | ![Dark Theme](images/docfx-pages-dark.png)\r\n\r\n\r\n\r\n## `HeaderDoc` Extraction\r\n\r\n`docfx-pages` provides feature to convert block comment at the beginning of source code to Markdown document. Those documents are automatically included into the generated API reference site.\r\n\r\n![HeaderDoc](images/HeaderDoc.png)\r\n\r\n\u003csup\u003e* When project contains only a single script, HeaderDoc won't be extracted.\u003c/sup\u003e\r\n\r\n\r\n\r\n## Usage\r\n\r\n```yaml\r\n- uses: sator-imaging/docfx-pages@v1\r\n  id: deployment   # required to show url in actions result page.\r\n  with:\r\n    # required parameters\r\n    app_name:    'docfx-pages'\r\n    site_title:  'Deploy using sator-imaging/docfx-pages'\r\n    site_footer: 'Copyright \u0026copy; \u003cem\u003e\u003cbig\u003eHTML\u003c/big\u003e Tags\u003c/em\u003e'\r\n    # optional parameters\r\n    class_members: ...\r\n```\r\n\r\n\r\n### Sample Outputs\r\n\r\n- `HeaderDoc` Page\r\n  - https://sator-imaging.github.io/docfx-pages/HeaderDocs/Tests/Program.cs.html\r\n  - C# Source Code\r\n    - https://github.com/sator-imaging/docfx-pages/blob/main/Tests/Program.cs\r\n- Built with `class_members: 'separatePages'` → [Go 🧾](https://sator-imaging.github.io/Unity-AltSourceGenerator/api/index.html)\r\n- Built with `class_members: 'samePage'` → [Go 🧾](https://sator-imaging.github.io/docfx-pages/api/index.html)\r\n  - *Note:* this sample demonstrates wrong result when specify `site_logo` or `site_favidon` as full-qualified URL. (Logo image in header is missing. `docfx` supports only relative path.)\r\n\r\n\r\n\r\n## Getting Started\r\n\r\nJust enable GitHub Pages in repository setting and paste the code below.\r\n\r\n![Repo Settings](images/repo-settings.png)\r\n\r\n\r\n### GitHub Actions Source Code\r\n\r\n\u003e [!TIP]\r\n\u003e 👇 Here is boilerplate-included sample code for GitHub Pages by Actions.\r\n\r\n\u003cp\u003e\u003cdetails open\u003e\r\n\r\n```yaml\r\nname: docfx for GitHub Pages\r\n\r\non:\r\n  # Runs on pushes targeting the default branch\r\n  push:\r\n    branches:\r\n      - 'main'\r\n      ##- 'releases/**'\r\n  release:\r\n    types: [published]\r\n\r\n  # Allows you to run this workflow manually from the Actions tab\r\n  workflow_dispatch:\r\n\r\n# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages\r\npermissions:\r\n  contents: read\r\n  pages: write\r\n  id-token: write\r\n\r\n# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.\r\n# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.\r\nconcurrency:\r\n  group: \"pages\"\r\n  cancel-in-progress: false\r\n\r\njobs:\r\n  # Single deploy job since we're just deploying\r\n  deploy:\r\n    environment:\r\n      name: github-pages\r\n      url: ${{ steps.deployment.outputs.page_url }}\r\n    runs-on: ubuntu-latest\r\n\r\n\r\n    #########################################\r\n    ######  sator-imaging/docfx-pages  ######\r\n    #########################################\r\n    steps:\r\n\r\n      # for extensibility, docfx-pages does NOT checkout your repository.\r\n      # so you need to checkout manually prior to sator-imaging/docfx-pages.\r\n      - name: Checkout\r\n        uses: actions/checkout@v4\r\n\r\n\r\n      # after checkout, you can checkout another repo, copy logo image or\r\n      # other assets into '.docfx' folder to setup your own docfx environment.\r\n      # note that images must be copied into '.docfx/images', 'images' or '.images'.\r\n\r\n\r\n      ######  main  ######\r\n\r\n      - uses: sator-imaging/docfx-pages@v1\r\n        id: deployment   # required to show url in actions result page.\r\n        with:\r\n\r\n          # required options\r\n          # NOTE: double-quote (\") cannot be used, backquote (`) must be escaped (\\`).\r\n          app_name:    'Deploy Test'\r\n          site_title:  'Deploy Test using sator-imaging/docfx-pages'\r\n          site_footer: '\u003cbig\u003e\u0026times; Is HTML accepted?\u003c/big\u003e'\r\n\r\n          # optional\r\n          class_members: 'separatePages'  # 'separatePages' or 'samePage'\r\n          google_analytics: ''  # empty to disable\r\n          define_symbols: ''  # additional preprocessor symbols separated by ';'\r\n\r\n          # paths must be relative from .docfx folder. default value is used when not set.\r\n          # note that url works but only in top page. see sample website for detail.\r\n          ###site_logo:    '\u003clogo\u003e.svg'\r\n          ###site_favicon: '\u003cfavicon\u003e.svg'\r\n\r\n          # advanced options\r\n          # --\u003e https://dotnet.github.io/docfx/docs/template.html?tabs=modern#custom-template\r\n          # main.js\r\n          # NOTE: double-quote (\") cannot be used, backquote (`) must be escaped (\\`).\r\n          main_js: |\r\n            export default {\r\n                defaultTheme: 'light',\r\n                showLightbox: (img) =\u003e true,\r\n                iconLinks: [\r\n                    {\r\n                        icon: 'github',\r\n                        href: 'https://github.com/sator-imaging',\r\n                        title: 'GitHub'\r\n                    },\r\n                ],\r\n            }\r\n\r\n          # main.css\r\n          # NOTE: double-quote (\") cannot be used, backquote (`) must be escaped (\\`).\r\n          main_css: |\r\n\r\n```\r\n\r\n\u003c/details\u003e\u003c/p\u003e\r\n\r\n\r\n\r\n## Advanced Usage\r\n\r\nFull customize can be done by adding `.docfx` folder to **your repository**.\r\n\r\nFor example, add logo image to `.docfx/images` folder in your repository.\r\n\r\n- `.docfx/images/\u003cyour-logo\u003e.svg`\r\n- `.docfx/images/\u003cyour-favicon\u003e.svg` or `.ico`\r\n\r\nthen, set options in your GitHub Actions. Note that paths must be relative from `.docfx` folder.\r\n\r\n```yaml\r\n- uses: sator-imaging/docfx-pages@v1\r\n  with:\r\n    site_logo:    'images/\u003cyour-logo\u003e.svg'\r\n    site_favicon: 'images/\u003cyour-favicon\u003e.ico'\r\n```\r\n\r\n\u003e [!NOTE]\r\n\u003e Default resource folders: `.docfx/images`, `images`, or `.images`\r\n\r\n\u003e [!TIP]\r\n\u003e You can prepare `.docfx` contents in your GitHub Actions instead of duplicating/uploading files in repository.\r\n\r\n\r\n\r\n## Builtin Assets\r\n\r\n- `images/wikimedia-commons/logo-csharp-recolor.svg`\r\n    - C# logo file for `site_logo` and `site_favicon`\r\n    - ![C# Logo](https://raw.githubusercontent.com/sator-imaging/docfx-pages/release/v1.0.0/.docfx/images/wikimedia-commons/logo-csharp-recolor.svg)\r\n- `images/unity/made-with-unity.svg`\r\n    - Theme-aware SVG file for `site_logo`\r\n    - ![Made with Unity](https://raw.githubusercontent.com/sator-imaging/docfx-pages/release/v1.0.0/.docfx/images/unity/made-with-unity.svg)\r\n\r\n\r\n\r\n## Technical Notes\r\n\r\n- `toc.yml` is automatically generated.\r\n- `README` or `README.md` is generated when doesn't exist.\r\n- `README.md` is used as fallback for `index.md`.\r\n- `LICENSE` or `LICENSE.md` document title is automatically set. (insert `#` at the beginning of first line)\r\n\r\n\r\n\r\n\u0026nbsp;  \r\n\u0026nbsp;\r\n\r\n## Devnote\r\n\r\n### Tests\r\n\r\nDue to GitHub Pages limitation, deploy action must be run on main branch.\r\n\r\nDevelopment branch has setted up to invoke main branch action indirectly by updating `test` tag. To do so, run the following command on dev branch to run tests.\r\n\r\n- `git pull; git tag -f test; git push --tags -f`\r\n\r\n\r\n### TODO\r\n\r\n- add `docfx_metadata`, `docfx_build` and `docfx_filter` options for easy customization.\r\n    - currently, it can be achieved by adding `.docfx` folder and place files correctly.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsator-imaging%2Fdocfx-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsator-imaging%2Fdocfx-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsator-imaging%2Fdocfx-pages/lists"}