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, is the most straightforward choice for python users. However, there are other noteworthy options like or . MkDocs Sphinx Pelican Let's begin: 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 . 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 . Make some changes to and save it. docs mkdocs serve index.md The configuration file has only two required fields and . By adding the field, you can specify the order and name of the navigation items. Even hierarchical navigation is supported out of the box. The last field defines where the website will be generated. It will be useful later on. site_name site_url nav site_dir 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 should now contain some static files. public mkdocs build ls public/ In case you are wondering which theme is using, it is . More custom themes can be found here . py.wiki mkdocs-material MkDocs Wiki: Themes Hosting your docs on GitLab GitLab provides a service called which enables to publish static websites directly from a GitLab repository. As an alternative, you could also use or . GitLab Pages Github Pages Cloudflare Pages Before initializing a git repository, please add the following lines to so that the build files will not be tracked. .gitignore site/ public/ We need the file for the CI/CD environment. requirements.txt 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 at the stage . public deploy Let's create a file in the root folder as follows: .gitlab-ci.yml 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: ... artifacts: paths: - public when: manual # <---- add this line Go to from the menu, you will see that this pipeline was skipped. If you click on the stage, you have the possibility to start this stage. Pipelines CI/CD Claiming a stylish domain When I came across JavaScript libraries with the domains , I noticed how easy the domains are to remember. Personally, I found that provides a great service for the JavaScript community, so I wanted to do something similar for the Python community. *.js.org js.org That is way I created the service , where people can register domains for Python-related projects. py.wiki *.py.wiki 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 in the menu and click on . Enter your desired domain name. After clicking on , the and fields are displayed. Remember this information. Pages Settings New Domain Create New Domain DNS Verification status Let's fork the repository . We have to extend the file . 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. py.wiki dns_config.yml 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: CNAME: py.wiki: name: bigaru.gitlab.io proxied: false Insert your domain in alphabetical order: 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: 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.
