\
If you are interested in publishing wikis, tutorials, or documentation of your project online, either you are confronted with installing and setting up a full-featured CMS like WordPress or learning HTML, JavaScript, and additionally a web framework.

\
I would like to show you another option, where you can simply create a website based on markdowns and publish it on free web hosting. And as a bonus, I will show you how to claim a free domain like *my-project.py.wiki*.

\
## Turning markdowns into a website

First, we need software that is able to turn markdowns into static web content. This software is called static site generators. In my personal experience, [MkDocs](https://www.mkdocs.org/) is the most straightforward choice for python users. However, there are other noteworthy options like [Sphinx](https://www.sphinx-doc.org/) or [Pelican](https://blog.getpelican.com/).

\
Let's begin:

\
```bash
pip install mkdocs
mkdocs new my-great-project
cd my-great-project
ls -R
```

\
The folder should look as follows:

\
```
mkdocs.yml    # The configuration file.
docs/         # contains all the markdowns
    index.md
```

\
Now you can move all markdowns to the folder *docs*. In fact, the dev-server supports auto-reloading, which means it detects the markdown changes and refreshes the page automatically. Let's start dev-server with *mkdocs serve*. Make some changes to *index.md* and save it.

\
The configuration file has only two required fields *site_name* and *site_url*. By adding the *nav* field, you can specify the order and name of the navigation items. Even hierarchical navigation is supported out of the box. The last field *site_dir* defines where the website will be generated. It will be useful later on.

\
```yaml
site_name: Foo Docs
site_url: https://foo.py.wiki/
nav:
  - Home: index.md
  - Dev Guide:
      - Setup: setup.md
      - Bug Report: bug_report.md
site_dir: public/
```

\
Let's generate it and the folder *public* should now contain some static files.

\
```bash
mkdocs build
ls public/
```

\
In case you are wondering which theme [py.wiki](https://py.wiki) is using, it is [mkdocs-material](https://github.com/squidfunk/mkdocs-material). More custom themes can be found here [MkDocs Wiki: Themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes).

\
## Hosting your docs on GitLab

GitLab provides a service called [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/) which enables to publish static websites directly from a GitLab repository. As an alternative, you could also use [Github Pages](https://pages.github.com/) or [Cloudflare Pages](https://pages.cloudflare.com/).

\
Before initializing a git repository, please add the following lines to *.gitignore* so that the build files will not be tracked.

\
```
site/
public/
```

\
We need the file *requirements.txt* for the CI/CD environment.

\
```bash
echo 'mkdocs==1.3.0' > requirements.txt
```

\
GitLab has a built-in CI/CD service. We now have to configure this service so that MkDocs generates the website in the folder *public* at the stage *deploy*.

\
Let's create a file `.gitlab-ci.yml` in the root folder as follows:

\
```yaml
image: python:3.10-bullseye

stages:
  - deploy

before_script:
  - pip install -r requirements.txt

pages:
  stage: deploy
  script:
    - mkdocs build --verbose
  artifacts:
    paths:
      - public
```

\
Now with each push on the remote branch, our documentation is built and published. After the first build, your website should be visible at `https://{username}.gitlab.io/{project-name}`.

\
In case you prefer to trigger the build process manually, you can add the following line:

\
```yaml
  ...
  artifacts:
    paths:
      - public
  when: manual # <---- add this line
```

\
Go to *Pipelines* from the *CI/CD* menu, you will see that this pipeline was skipped. If you click on the stage, you have the possibility to start this stage.

\
 ![CI stage detail](https://cdn.hackernoon.com/images/yC0oW9wRqBUwVyA4yPYcAhTARb13-ufa2h7j.png)

\
## Claiming a stylish domain

When I came across JavaScript libraries with the domains `*.js.org`, I noticed how easy the domains are to remember. Personally, I found that [js.org](http://js.org) provides a great service for the JavaScript community, so I wanted to do something similar for the Python community.

\
That is way I created the service `py.wiki`, where people can register domains `*.py.wiki`  for Python-related projects.

\
Think of a suitable domain. Below are some ideas on how to determine the appropriate domain name:

* if library "foo-bar" => foo-bar.py.wiki
* if library "foopy" => foo.py.wiki
* if gitlab page "foo.github.io/bar" => foo.py.wiki
* if gitlab page "foo.github.io/bar" => bar.py.wiki

\
Go to *Pages* in the *Settings* menu and click on *New Domain*. Enter your desired domain name. After clicking on *Create New Domain*, the *DNS* and *Verification status* fields are displayed. Remember this information.

\
 ![GitLab Pages - new domain](https://cdn.hackernoon.com/images/yC0oW9wRqBUwVyA4yPYcAhTARb13-edb2hsp.png)

\
Let's fork the repository [py.wiki](https://gitlab.com/bigaru/py.wiki). We have to extend the file `dns_config.yml`. There 2 ways to add our domain under CNAME. With the first approach, the Cloudflare proxy is automatically enabled, which means Cloudflare will cache the content of your website.

\
```yaml
CNAME:
  py.wiki: bigaru.gitlab.io
```

\
In case you do not want that your content is cached, you can disable the Cloudflare proxy as follows:

\
```yaml
CNAME:
  py.wiki:
    name: bigaru.gitlab.io
    proxied: false
```

\
Insert your domain in alphabetical order:

\
```yaml
CNAME:
  foo.py.wiki: foo.gitlab.io
  py.wiki: bigaru.gitlab.io
  www.py.wiki:
    name: bigaru.gitlab.io
    proxied: true
```

\
In the case of GitLab Pages, we additionally need to add a TXT record to verify the ownership. Therefore, simply append with your entry to TXT:

\
```yaml
TXT:
  _gitlab-pages-verification-code.py.wiki: gitlab-pages-verification-code=0000
  _gitlab-pages-verification-code.www.py.wiki: gitlab-pages-verification-code=0000
  _gitlab-pages-verification-code.foo.py.wiki: gitlab-pages-verification-code=0000
```

\
After saving and pushing to the remote branch, let's open a new merge request. Choose the template 'new-domain'. Afterward, fill out the form and create the merge request.

\
Once your merge request is accepted and merged, the CI server will automatically update the DNS records on Cloudflare. The DNS probation may take some time. Thereafter, your page will be accessible under a fancy domain.

Read My Stories

Too Long; Didn't Read

Build an AI-based text classifier with Tensorflow & NoSQL

Rapid Way to Publish Python Docs With Free Hosting and Domain

Too Long; Didn't Read

@bigaru

RELATED STORIES