Include gh-import source in MkDocs to solve windows path issues.

[w3guy]

I wana publish my doc to a github page, i can't seem to get it to work with mkdocs gh-deploy but i know how to do with via

Checking out the gh-pages branch and committing the site folder to GitHub.

[d0ugal]

Not really, there is very little to it. What happens when you run mkdocs gh-deploy?

[w3guy]

It shows deploy successful but doesn't show up in GitHub

On Sat, May 23, 2015 at 2:14 PM, Dougal Matthews notifications@github.com
wrote:

Not really, there is very little to it. What happens when you run mkdocs
gh-deploy?

—
Reply to this email directly or view it on GitHub
#547 (comment).

[d0ugal]

What URL does the go and display? What repo is it? Send over as many details as you can.

[waylan]

@collizo4sky has a point. There are absolutely no instructions anywhere for how to use ghp-deploy. For example, he could be missing any of the following (which I agree all seem obvious because I know how it works--but to a newcomer, maybe not so much):

1. Clone the relevant repo from Github
2. Checkout the branch which holds the unrendered docs (not the gh-pages branch).
3. Make sure the docs render properly (using mkdocs build and/or mkdocs serve). If not, fix, commit, and push your changes (not to the gh-pages branch).
4. From within the working tree of your repo (not the gh-pages branch), run mkdocs ghp-deploy.

That's it. The deploy command will build the docs, commit them to the gh-pages branch, and push the gh-pages branch to Github for you all in one step. It is important to note that "You should never edit files in your gh-pages branch by hand if you're using this script because you will lose your work."

That last sentence was taken directly from the docs for the ghp-import tool, which mkdocs uses under the hood. And while ghp-import does not push by default, mkdocs ghp-deploy does (and in fact the default behavior cannot be overridden--which may or may not be a good idea).

[w3guy]

‎I totally was doing this wrong.What I did was,* checkout the gh-branch* copy the content of the site folder‎ to the local branch* run gh-deployThank you for taking time to explain.I will give it a try and get back to you. From: Waylan LimbergSent: Sunday, 24 May 2015 3:44 AMTo: mkdocs/mkdocsReply To: mkdocs/mkdocsCc: Agbonghama CollinsSubject: Re: [mkdocs] Is there a guide to using gh-deploy ? can't get it to work (#547)@collizo4sky has a point. There are absolutely no instructions anywhere for how to use ghp-deploy. For example, he could be missing any of the following (which I agree all seem obvious because I know how it works--but to a newcomer, maybe not so much):

Clone the relevant repo from Github
Checkout the branch which holds the unrendered docs (not the gh-pages branch).
Make sure the docs render properly (using mkdocs build and/or mkdocs serve). If not, fix, commit, and push your changes (not to the gh-pages branch).
From within the working tree of your repo (not the gh-pages branch), run mkdocs ghp-deploy.

That's it. The deploy command will build the docs, commit them to the gh-pages branch, and push the gh-pages branch to Github for you all in one set. It is important to note that "You should never edit files in your gh-pages branch by hand if you're using this script because you will lose your work."

That last sentence was taken directly from the docs for the ghp-import tool, which mkdocs uses under the hood. And while ghp-import does not push by default, mkdocs ghp-deploy does (and in fact the default behavior cannot be overridden--which may or may not be a good idea).

—Reply to this email directly or view it on GitHub.

[d0ugal]

Sure, so we need to cover this workflow in detail when we do #477.

[w3guy]

Hi, i still can't get it to work.

BreakDown

The master branch of https://github.com/ProfilePress/documentation/ stores the mkdocs files with all the markdown files in doc folder

The gh-branch of that repo is the branch for the Github page.

Each time i run the mkdocs gh-deploy command, i get this

$ mkdocs gh-deploy
Building documentation to directory: site
Directory site contains stale files. Use --clean to remove
Copying 'site' to `gh-pages` branch and pushing to GitHub.

But the gh-branch is being updated @waylan

[d0ugal]

@collizo4sky How are your git remotes configured? You can see this with git remote -v

[d0ugal]

Oh, horrible. You must be hitting this I guess: https://github.com/mkdocs/mkdocs/blob/0.12.2/mkdocs/gh_deploy.py#L19

[w3guy]

This was what i got after running git remote -v

origin  https://github.com/ProfilePress/documentation.git (fetch)
origin  https://github.com/ProfilePress/documentation.git (push)

Any idea?

[d0ugal]

Aha! It's https I wonder if that could be a problem, I'd expect to see SSH. Can you push the branch manually okay?

git push origin gh-pages

If it asks for a username and password, I bet it wont work with MkDocs.

[d0ugal]

There is a bit more info about this here: https://help.github.com/articles/which-remote-url-should-i-use/

[w3guy]

It didnt ask for a username or password cos i already have lookup the credentials from .git-credential file.

It says everything s up to date when i ran the command.