gh-deploy not using material theme

[flywire]

How can the site be rendered directly from /docs with mkdocs-material theme?

mkdocs gh-deploy --force creates user.github.io/repo/site but user.github.io/repo renders user.github.io/repo/docs/index.mdwithout mkdocs-material theme (ie vanilla mkdocs).

If source is set to root user.github.io/repo/site/index.html renders with mkdocs-material theme.

Following mkdocs-material getting-started using minimal deploy:

pip install mkdocs-material
mkdocs new .
mkdocs build
rem from the directory containing the mkdocs.yml file:
mkdocs gh-deploy --force

[Andre601]

The default setup of MkDocs should properly work when you run the gh-deploy command, as that would build the contents in the docs directory and push it to the gh-pages branch of the Repository you defined.

My best guess here is, that you seem to have misconfigured something, as the only reason for the site directory to be included would be that you changed the build-directory that mkdocs should build.

When using mkdocs new . should the structure look like this:

|
|- docs/
|    |- index.md
|
|- mkdocs.yml

Did you double-check that it is like this?
Also, what is the current mkdocs.yml configuration you have?

You also need to define MkDocs material as an actual theme for MkDocs to use. It's not included by default.

[flywire]

You've misunderstood my comment.

1. on PC mkdocs serve uses material theme under localhost:8000
2. https://flywire.github.io/test2/ does not use material theme

Process is scripted below and repo exists.

repo-issue.bat

set user=flywire
if %user%!==! goto end
md %1
cd %1
mkdocs new .
echo theme: >> mkdocs.yml
echo   name: material >> mkdocs.yml
rem optional check: mkdocs serve
git init
git add .
echo *.bak >.gitignore
git commit -m "Initial commit"
echo login to github and create new repository with nothing in it
pause
git remote add origin  https://github.com/%user%/%1.git
git push -u origin main
echo In GitHub repo Settings, Pages enable main /docs
pause
rem from the directory containing the mkdocs.yml file:
mkdocs gh-deploy --force
:end

log

Microsoft Windows [Version 10.0.19043.1165]
(c) Microsoft Corporation. All rights reserved.

E:\repo>repo-issue test2

E:\repo>set user=flywire

E:\repo>if flywire! == ! goto end

E:\repo>md test2

E:\repo>cd test2

E:\repo\test2>mkdocs new .
INFO     -  Writing config file: .\mkdocs.yml
INFO     -  Writing initial docs: .\docs\index.md

E:\repo\test2>echo theme:  1>>mkdocs.yml

E:\repo\test2>echo   name: material  1>>mkdocs.yml

E:\repo\test2>rem optional check: mkdocs serve

E:\repo\test2>git init
Initialized empty Git repository in E:/repo/test2/.git/

E:\repo\test2>git add .

E:\repo\test2>echo *.bak  1>.gitignore

E:\repo\test2>git commit -m "Initial commit"
[main (root-commit) a28b8b7] Initial commit
 2 files changed, 20 insertions(+)
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

E:\repo\test2>echo login to github and create new repository with nothing in it
login to github and create new repository with nothing in it

E:\repo\test2>pause
Press any key to continue . . .

E:\repo\test2>git remote add origin  https://github.com/flywire/test2.git

E:\repo\test2>git push -u origin main
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (5/5), 613 bytes | 613.00 KiB/s, done.
Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/flywire/test2.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

E:\repo\test2>echo In GitHub repo Settings, Pages enable main /docs
In GitHub repo Settings, Pages enable main /docs

E:\repo\test2>pause
Press any key to continue . . .

E:\repo\test2>rem from the directory containing the mkdocs.yml file:

E:\repo\test2>mkdocs gh-deploy --force
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: E:\repo\test2\site
INFO     -  Documentation built in 0.28 seconds
←[33mWARNING  -  ←[0mVersion check skipped: No version specified in previous deployment.
INFO     -  Copying 'E:\repo\test2\site' to 'gh-pages' branch and pushing to GitHub.
Enumerating objects: 47, done.
Counting objects: 100% (47/47), done.
Delta compression using up to 8 threads
Compressing objects: 100% (43/43), done.
Writing objects: 100% (47/47), 270.89 KiB | 5.21 MiB/s, done.
Total 47 (delta 5), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (5/5), done.
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/flywire/test2/pull/new/gh-pages
remote:
To https://github.com/flywire/test2.git
 * [new branch]      gh-pages -> gh-pages
INFO     -  Your documentation should shortly be available at: https://flywire.github.io/test2/
E:\repo\test2>

[flywire]

https://www.mkdocs.org/user-guide/deploying-your-docs/#github-pages

Project Pages sites are simpler as the site files get deployed to a branch within the project repository (gh-pages by default).

GitHub pages default is main. Mkdocs documentation needs fixing.

[pawamoy]

GitHub pages default is main.

I never need to change anything in a new repo pages settings to publish pages on the gh-pages branch using MkDocs. Can you show GitHub's docs where they say the main branch is the default for GitHub pages? In this help page, what is shown is that pages are disabled by default, not set up on the main branch.

[pawamoy]

I never need to change anything

Or maybe I do and don't remember? In any case, by default pages are disabled, so you just have to pick the gh-pages branch when enabling them. I think MkDocs documentation is correct.

[Andre601]

https://www.mkdocs.org/user-guide/deploying-your-docs/#github-pages

Project Pages sites are simpler as the site files get deployed to a branch within the project repository (gh-pages by default).

GitHub pages default is main. Mkdocs documentation needs fixing.

It's not.
You get it confused with a user/org page repo (:username/:username.github.io)

By default is the gh-pages branch used for any other repo.

[flywire]

Create new repo and go to Settings, Pages ... only option is main

[Andre601]

Create new repo and got to Settings, Pages ... only option is main

That's because the branch needs to be created.
Please learn the basics before sharing half-truths

[flywire]

That's because the branch needs to be created.

Edit: the following line in the original script is wrong and prevents the site from loading
echo In GitHub repo Settings, Pages enable main /docs

Please learn the basics before sharing half-truths

A user shouldn't have to know anything to follow a tutorial. I even scripted the commands.

Maybe I just didn't wait long enough for the site to appear before setting it to the wrong branch.

[pawamoy]

Not sure to understand your last sentence. Comment edited.

I just tried it myself: I created a new repository on GitHub, and didn't touch anything in the settings.
Then I cloned it, intialized an MkDocs site in it, gh-deployed it, and GitHub automatically detected my gh-pages branch.

% git clone git@github.com:pawamoy/see-what-the-default-branch-is-for-gh-pages
Cloning into 'see-what-the-default-branch-is-for-gh-pages'...
warning: You appear to have cloned an empty repository.

% cd see-what-the-default-branch-is-for-gh-pages 
% mkdocs new .
INFO     -  Writing config file: ./mkdocs.yml
INFO     -  Writing initial docs: ./docs/index.md

% echo 'site' > .gitignore
% mkdocs build
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/pawamoy/see-what-the-default-branch-is-for-gh-pages/site
INFO     -  Documentation built in 0.04 seconds

% git status -sb
## No commits yet on master...origin/master [gone]
?? .gitignore
?? docs/
?? mkdocs.yml

% git add . -A
% git commit -m "add docs"  # committing on main/master is not even needed to deploy docs
[master (root-commit) 744f1b5] add docs
 3 files changed, 19 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

% mkdocs gh-deploy
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/pawamoy/see-what-the-default-branch-is-for-gh-pages/site
INFO     -  Documentation built in 0.04 seconds
WARNING  -  Version check skipped: No version specified in previous deployment.
INFO     -  Copying '/home/pawamoy/see-what-the-default-branch-is-for-gh-pages/site' to 'gh-pages' branch and pushing to GitHub.
Enumerating objects: 29, done.
Counting objects: 100% (29/29), done.
Delta compression using up to 6 threads
Compressing objects: 100% (28/28), done.
Writing objects: 100% (29/29), 607.80 KiB | 4.94 MiB/s, done.
Total 29 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), done.
To github.com:pawamoy/see-what-the-default-branch-is-for-gh-pages
 * [new branch]      gh-pages -> gh-pages
INFO     -  Your documentation should shortly be available at: https://pawamoy.github.io/see-what-the-default-branch-is-for-gh-pages/

As you can see, GitHub even returns a message in a git INFO line stating the documentation will be shortly available. It is now: https://pawamoy.github.io/see-what-the-default-branch-is-for-gh-pages/.

Now let's see if it works if I set the material theme:

% echo -e 'theme:\n  material' >> mkdocs.yml 
% git status -sb
## master...origin/master [gone]
 M mkdocs.yml

% git diff
modified: mkdocs.yml
@ mkdocs.yml:1 @
 site_name: My Docs
+theme:
+  material

# at this point mkdocs-material is already installed and available to mkdocs

% mkdocs build  # not even needed, just to check if it builds ok
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/pawamoy/see-what-the-default-branch-is-for-gh-pages/site
INFO     -  Documentation built in 0.17 seconds

% mkdocs gh-deploy
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/pawamoy/see-what-the-default-branch-is-for-gh-pages/site
INFO     -  Documentation built in 0.11 seconds
INFO     -  Copying '/home/pawamoy/see-what-the-default-branch-is-for-gh-pages/site' to 'gh-pages' branch and pushing to GitHub.
Enumerating objects: 53, done.
Counting objects: 100% (53/53), done.
Delta compression using up to 6 threads
Compressing objects: 100% (45/45), done.
Writing objects: 100% (48/48), 444.00 KiB | 3.17 MiB/s, done.
Total 48 (delta 7), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (7/7), completed with 1 local object.
To github.com:pawamoy/see-what-the-default-branch-is-for-gh-pages
   ccf94f2..cbfd01e  gh-pages -> gh-pages
INFO     -  Your documentation should shortly be available at: https://pawamoy.github.io/see-what-the-default-branch-is-for-gh-pages/

And my docs are now themed with material: https://pawamoy.github.io/see-what-the-default-branch-is-for-gh-pages/.

Everything seems to work correctly.

[flywire]

#2569 (reply in thread)