doxygen documentation deployed successfully to GitHub Pages but getting 404 page not found error

Question

I am trying to build the Doxygen documentation and publish it to GitHub Pages. Generally, I build the static HTML and CSS files, generate them, and push them with the repository. Then, I use a custom static action to publish the files to GitHub Pages. I want to automate the build and publishing process without needing to push the static web pages along with the code. So, I modified my old GitHub Action script as follows

name: build-docs
on:
  push:
    branches: ["main"]
permissions:
  contents: write
  pages: write
  id-token: write
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install Doxygen
        run: |
          sudo apt-get update 
          sudo apt-get install -y doxygen
      - name: Install Graphviz
        run: sudo apt-get install -y graphviz
      - name: Create docs directory
        run: mkdir -p ./docs/html
      - name: Run Doxygen to generate documentation
        run: doxygen ./docs/Doxyfile
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './docs/html'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Here, everything works fine, and all build logs output successfully, but when I go through the created domain, I get a 404 error: 404 error.
This is the repository: https://github.com/wissem01chiha/tinyurdf
The Pages settings are set to deployment from GitHub Actions.

I tried changing the GitHub Pages settings from the repository settings, setting the environment, and deleting it (the repository has no secrets or environment variables—I don’t have much idea about what this does).

I also tried adding a custom run job to the workflow to inspect the generated files and download the artifact. Everything seems fine (the generated web files are correct), but the publish step fails without giving any reasonable output or error!

Azeem · Accepted Answer · 2025-01-22 08:20:41Z

2

In docs/Doxyfile, OUTPUT_DIRECTORY is configured twice:

OUTPUT_DIRECTORY        = ./       # Line 9
OUTPUT_DIRECTORY = ./docs/html     # Line 38

See:

Due the the last one, the output is generated under:

docs/html/html

and, not under:

docs/html

As the GitHub Pages deployment is from docs/html, there's no index.html here hence the 404 Page not found error.

So, with the current configuration:

https://wissem01chiha.github.io/tinyurdf (404 Page Not Found) - Not working!
https://wissem01chiha.github.io/tinyurdf/html (200 OK) - Working!

Changing OUTPUT_DIRECTORY to ./docs on line 9 and removing/commenting line 38 should resolve this issue:

OUTPUT_DIRECTORY = ./docs          # Line 9

Also, no need to create ./docs/html directory in the workflow i.e.:

- name: Create docs directory
  run: mkdir -p ./docs/html

It'll automatically be created by doxygen.

Alternatively, updating path in the workflow should also work:

path: './docs/html/html'

edited Jan 22 at 8:20

answered Jan 22 at 7:15

Azeem

15.1k4 gold badges36 silver badges53 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

JensV Jan 22 at 7:24

Are you sure about that? I would've assumed it was due to the missing trailing slash in the path of the CI config

Azeem Jan 22 at 7:57

@JensV: Yes. Tested and verified.

JensV Jan 22 at 8:34

Indeed, can reproduce it too +1

wissem chiha Jan 22 at 11:19

Ah thanks very very much, that resolved the issue, i didn't pay attention to the Doxyfile, since i was looking for the github-action file, well done,

Collectives™ on Stack Overflow

doxygen documentation deployed successfully to GitHub Pages but getting 404 page not found error

1 Answer 1

4 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

4 Comments

Your Answer

Sign up or log in

Post as a guest

Related