Deploying on Github pages - assets not showing up

[tomtalp]

Hello, I'm having some trouble with setting up my page with Github pages.

In my project, I have all my files in ./docs/, and my mkdocs.yml in the main dir, and myy ci.yml file is exactly like the docs.

In the GitHub pages settings, I have tried setting the root dir to either / (root) and /docs -

or

and I have tried setting site_url in mkdocs.yml to either -

• <username>.github.io/<repository>
• <username>.github.io/<repository>/docs

In all these cases, the website appears with out the assets - I am just seeing blank markdown files. (link)

What exactly should I set as site_url?
What dir should I choose in the GitHub pages settings? root? /docs?
Anything else that I missed?

Thanks in advance

[alexvoss]

Your site is being built with Jekyll, not Material for MkDocs. I am not terribly familiar with GitHub Pages but one thing I wonder if whether your ci.yml file is in the correct path. AFAIK, it should be in a .github subdirectory unter your project root.

[tomtalp]

The ci.yml file is located in /my_project/.github/workflows/ci.yml , which is according to the docs. (https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions)

But maybe my mkdocs.yml file is misplaced?
Right now it's in the main directory - github.com/tomtalp/pyERGM/mkdocs.yml

here's the file -

site_name: pyERGM
site_url: https://tomtalp.github.io/pyERGM/
theme:
  name: material
  palette:
    scheme: default
    primary: blue

nav:
  - Home: index.md
  - Overview: overview.md
  - Fitting a model: fitting.md
  - Evaluating model performance: evaluating.md
  - Metrics:
    - Introduction to graph metrics: metrics.md
    - List of metrics: metrics_reference.md
    - Creating custom metrics: custom_metrics.md
    

markdown_extensions:
  - pymdownx.superfences 
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

repo_name: 'pyERGM'
repo_url: 'https://github.com/tomtalp/pyERGM'

Thanks

[kamilkrzyskow]

Hello @tomtalp,
your CI file uses mkdocs gh-deploy to deploy the docs. The default behaviour is to use the gh-pages branch on your repository to store the built site.

• https://github.com/tomtalp/pyERGM/blob/f080fc853dc84cf8892d0a064139c1bd58e9a42d/.github/workflows/ci.yml#L30
• https://www.mkdocs.org/user-guide/deploying-your-docs/

So your screenshot is incorrect:

Your README_docs branch contains the source files for your MkDocs documentation, while the built site from mkdocs build would go to the site directory as per the .gitignore and no custom set site_dir in your mkdocs.yml file:

• https://github.com/tomtalp/pyERGM/blob/f080fc853dc84cf8892d0a064139c1bd58e9a42d/.gitignore#L150

But again, you're using mkdocs gh-deploy, so change your GitHub Pages to use the root / of the gh-pages branch:

• https://github.com/tomtalp/pyERGM/tree/gh-pages

Note

You might not want to use an gh-pages branch on your repository to store the site. There are other ways like using a special GitHub Action to upload the mkdocs build site directory directly to the GitHub Pages workspace, but that's a separate endeavour you might be interested to investigate, as it's not documented in the docs, but is being used by the theme's documentation itself.

[kamilkrzyskow]

The <username>.github.io/<repository>/ site_url is ok 👍

[tomtalp]

Great! Indeed changing to the gh-pages branch solves the issue.
Thank you very much.