> For the complete documentation index, see [llms.txt](https://stalwartcoder.gitbook.io/abhishek-notes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stalwartcoder.gitbook.io/abhishek-notes/mkdocs-github-gh-pages-deploy-trick.md).

# MkDocs github/ gh-pages deploy trick

#### **Disclaimer:** 

> `mkdocs build` doesn't allow the build of the `/site` within the same directory, hence the traditional gh-pages  deployment settings will fail and it won't deploy your site. (if its a org or user based pages)
>
> Hence the follwoing trick should work. 

If the output of your MkDocs build is in the `/site` folder, you need to push the contents of this folder to the `gh-pages` branch of your GitHub repository. However, you should not push the `/site` the directory itself but its contents. Here's how you can do it:

1. **Ensure Your Local Repository is Updated**:
   * Make sure your local repository is up to date with the main branch.
   * Build your MkDocs site using `mkdocs build`. This will update the `/site` directory.
2. **Move to the `/site` Directory**:
   * Navigate to the `/site` directory in your local repository.
3. **Create a Temporary Git Repository**:
   * Since the `/site` the directory is not a Git repository, you need to initialize it temporarily:

     ```
     cd site
     git init
     ```
4. **Commit the Changes**:
   * Add and commit the changes in the `/site` directory:

     ```
     git add .
     git commit -m "Deploy MkDocs Site"
     ```
5. **Push to `gh-pages` Branch**:
   * Push the contents of the `/site` directory to the `gh-pages` branch of your remote repository. Replace `your-username` with your GitHub username.

     ```
     git push -f https://github.com/mumbaipy/website.git master:gh-pages
     ```
6. **Clean Up**:
   * Once you've successfully pushed to `gh-pages`, you can delete the temporary Git repository in the `/site` directory:

     ```
     rm -rf .git
     ```
7. **Configure GitHub Pages**:
   * Go to your repository (`https://github.com/mumbaipy/website`).
   * Click on 'Settings' and scroll down to the 'GitHub Pages' section.
   * Set the source to the `gh-pages` branch.
8. **Access Your Site**:
   * Your MkDocs site should now be available at `https://mumbaipy.github.io/website/`.

This process ensures that the built HTML files in your `/site` directory are pushed to the `gh-pages` branch, allowing GitHub Pages to host your MkDocs site. Remember to repeat these steps every time you update your site.