Project logo does not show in MKDocs pages

The logo needs to be placed inside the docs folder. For gitlab_templates, we are just duplicating the image.

Thanks. I was just inspecting the source, and saw this '404 not found' error on https://project.pages.drupalcode.org/scheduler/logo.png and was going to ask how we get files there.

Would it be useful to add a line about this into the MkDocs page?

Yes, we could add a section for this in this page https://project.pages.drupalcode.org/gitlab_templates/jobs/pages/

Given that this is also a special file, we could even consider copying it directly during the CI job. If the file exist in the root of the repo and does not exist in the docs folder, then copy it.

Good idea to test that. I changed the mkdocs.yml

theme:
  logo: ../logo.png
  favicon: ../logo.png

but it did not make any difference.

I like the idea of copying the logo file in the 'pages' job, and I think it should be done regardless of whether it already exists in docs folder. The two files should always be the same, there is no reason for a different logo version in the documentation site. But more importantly, if it is only copied the first time, then the maintainer modifies the logo, they will not know why the docs site still has the old version. It is better to keep them always synchronized.

I've pushed an initial change, not tested yet, but will try it out with Scheduler, using a modifed 'pages' that runs on MRs not just commits to the default branch.

I naively added test -f logo.png && cp -v logo.png docs/logo.png into the page job, and of course this does copy the file within the pipeline job, but that has no permanent effect. Do we need to use $CI_MERGE_REQUEST_PROJECT_URL which contains https://git.drupalcode.org/project/{the-project} then append /docs ?

The two files should always be the same, there is no reason for a different logo version in the documentation site

Maybe there is a reason for the logo to be different. For example, you might want to use a color variation as default but then another variant of it that matches with the default blue of mkdocs. I think that if the maintainer has put a logo in the folder, we should respect it.

We can add this logic to the documentation or even add some output to the job so maintainers who check it see that it's a possibility.

I would have thought that the cp would have a permanent effect as the public directory is built from there. I don't think we need to play with the URLs.

OK, fair enough. Yes I will add the check not to overwrite, and give a message if not doing so.

I would have thought that the cp would have a permanent effect as the public directory is built from there. I don't think we need to play with the URLs.

Maybe the file did not appear to be copied on my test because it was running in a MR branch. I changed the 'pages' rules in a custom override, as normally it only runs on commit to default branch. The documentation pages were updated this way, but the image was not copied. It would be nice to test this change somehow before commiting, but now sure how I can do that.

I think you're testing here: https://git.drupalcode.org/project/scheduler/-/merge_requests/209/diffs
Can you change:

  logo: ../logo.png
  favicon: ../logo.png

Back to:

  logo: logo.png
  favicon: logo.png

ha ha, that's a silly mistake. Thank you! I was testing what you said above, but forgot to revert it.
The file had been copied to https://project.pages.drupalcode.org/scheduler/logo.png now, but just not showing in the docs page.

Maybe we need to copy it to the public folder? I guess we can copy it after the mkdocs command.

Indeed, it seems that you were copying the file to the docs folder after running mkdocs on your MR.

We have two options:
- Copying the file to docs before running mkdocs
- Copying the file to public after running mkdocs

You might need to hard refresh, but the logo is there already:

Indeed, it seems that you were copying the file to the docs folder after running mkdocs on your MR.

Yes, I was playing around with the sequence. The logic for copying the file might work better than I first thought it would. When copying just to /docs before calling mkdocs the file is used but is not permanently stored in the repo /docs which is good, because that means if the maintainer has not created an alternative then the main logo file is changed it will get copied again. I have re-run the pipeline and each time it shows /docs/logo.png does not exist, and proceeds to copy the file.

Now need to test what happens when a file is stored in the repo /docs

That works. I added a different logo.png to /docs in the MR and the log shows

$ pwd && ls -la logo* && ls -la docs/logo* || true
/builds/project/scheduler
-rw-rw-rw- 1 root root 11897 Nov 12 17:05 logo.png
-rw-rw-rw- 1 root root 17790 Nov 12 17:05 docs/logo.png
$ if [[ -f logo.png ]]; then # collapsed multi-line command
logo.png not copied to /docs because that file already exists.

The docs site is now rebuilt with the alternative logo as required

Test when logo.png does exist in /docs folder
https://git.drupalcode.org/project/scheduler/-/jobs/3333337
This produces the result as shown in #17 with the alternative rainbow ring logo

Test when logo.png does not exist in /docs folder
https://git.drupalcode.org/project/scheduler/-/jobs/3334239
This produces the result as shown in #15 above.

I suggest that the pwd && ls can stay in, as that gives useful info in the 'pages' log, given that we are manipulating those files.

Ready for review.

The logic looks good and the tests also prove that it works. RTBC.

Merged. Thanks!

Automatically closed - issue fixed for 2 weeks with no activity.