MkDocs is an open-source static site generator that is used to create documentation websites. It is written in Python and is built on top of the Jinja2 template engine. It uses Markdown files as the source for the documentation, and it generates a static HTML website that can be hosted on any web server.
MkDocs is a great tool for creating professional-looking documentation websites for your projects, and it’s widely used in open-source communities and enterprise organizations.
MkDocs allows you to easily organise your documentation into sections and pages and supports features like search, navigation, and theme customisation. It also provides a built-in development server that lets you preview your documentation while working on it.
Netlify is a popular static site hosting serverless platform. It is a popular way to build, deploy, and scale modern web applications in a much more scalable and secure way.
- The developer writes code and stores it in a version control repository (e.g. GitHub).
- When a new change is merged into the main branch of the repository, a webhook notifies Netlify to deploy a new site.
- Netlify pulls the latest version of the app from the repository and runs a build command to generate the static site files
- Netlify then uses Plugins and internal code to make adjustments to your site, pre-render all of your pages in static HTML and improves it further /
- Once the build process gets completed, Netlify takes the static assets and pushes them to its global CDN for fast delivery.
MkDocs and Netlify work together to create and deploy a static documentation website. Here is how the process typically works:
- You create your documentation using Markdown files and organize them into sections and pages using MkDocs.
- You run the command
mkdocs buildto generate a static HTML website from the Markdown files.
- You push the generated HTML website and your source files to a source control repository (e.g. GitHub, GitLab, Bitbucket)
- You set up a new site in Netlify and connect it to your source control repository.
- You configure the build settings in Netlify to run the command mkdocs build and specify the output directory as the publish directory.
- When you push changes to your source control repository, Netlify will automatically build and deploy the updated documentation website.
This way, you can easily manage your documentation in Markdown and preview it locally with the built-in development server of mkdocs. And when you’re ready to deploy it, you can push it to your source control repository and let Netlify handle the build and deployment process.
With this setup, you can easily make updates to your documentation and deploy them to your website without needing to manually upload files or configure a web server.
It’s also worth mentioning that you can use Netlify’s caching feature to speed up the build process and to make sure that your site is served as quickly as possible.
- Apple Mac/Linux/Windows
- A GitHub Account
- A Netlify Account
- GitHub Repository configured with Netlify
- Python 3.6
MkDocs can be easily installed via pip and configured using a simple YAML configuration file. It also provides a command-line interface (CLI) that allows you to build, preview, and deploy your documentation with a few simple commands.
To install MkDocs, run the following command from the command line:
pip install mkdocs
Getting started is super easy. To create a new project, run the following command from the command line:
mkdocs new dockerlabs cd dockerlabs
There’s a single configuration file named
mkdocs.yml, and a folder named docs that will contain your documentation source files (docs is the default value for the docs_dir configuration setting). Right now the docs folder just contains a single documentation page, named
MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you’re in the same directory as the
mkdocs.yml configuration file, and then start the server by running the mkdocs serve command:
$ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 [I 160402 15:50:43 handlers:58] Start watching changes [I 160402 15:50:43 handlers:60] Start detecting changes
Customising your site
Now that we’ve got a basic site set up with MkDocs, it’s time to customize the site.
mkdocs.yaml and you will able to add below:
Naming your Site
site_name setting to “Nilesh Dalvi” and save the file.
Add pages to Site
Add an order, title, and nesting of each page in the navigation header by adding a
site_name: Collabnix site_url: https://dockerlabs.collabnix.com/ nav: - Home: index.md
Theme your Site
site_name: Collabnix site_url: https://dockerlabs.collabnix.com/ nav: - Home: index.md - Installation: - Installing Docker Desktop for Linux: docker-desktop-for-linux.md - Installing Docker Desktop for Windows: docker-desktop-for-windows.md - Installing Docker Desktop for Mac: docker-desktop-for-mac.md - Installing Docker on Raspberry Pi: docker-on-raspberrypi.md - Installing Docker on NVIDIA Jetson: docker-on-jetson-nano.md - Getting Started with Docker Hub: - Creating Your Docker Hub Account: docker-hub.md - Getting Started with Docker Image: - Running Hello World Example: hello-world.md - Working with Docker Image: working-with-docker-image.md - Saving Images and Containers as tar files: saving-images-and-containers.md - Building Your First Alpine Docker Image: building-first-alpine.md theme: readthedocs
Building Your Site
Step 3. Accessing the static site
http://localhost:8000 to access the site.
First, we need to initialize a new Python project. We will be using Poetry. Poetry is a dependency management tool and packaging system for Python. It allows developers to manage their project dependencies and package their projects for distribution, similar to tools like pip and virtualenv.
“poetry init” is a command used in the terminal to initialize a new Python project with Poetry. When you run the command “poetry init” in the terminal while in a directory, it will create a new directory with the same name as the current one and initialize a new Python project in it with Poetry. This command will also create a new file called “pyproject.toml” which is used to specify the dependencies for the project. Additionally, “poetry init” can also be used to convert an existing Python project to use Poetry by generating a pyproject.toml file.
poetry init This command will guide you through creating your pyproject.toml config. Package name [dockerlabs]: dockerlabs Version [0.1.0]: 1.0.0 Description : Author [Ajeet Singh Raina <ajeetraina@Docker-Ajeet-Singh-Rainas-MacBook-Pro.local>, n to skip]: License : MIT Compatible Python versions [^3.10]: Would you like to define your main dependencies interactively? (yes/no) [yes] yes You can specify a package in the following forms: - A single name (requests): this will search for matches on PyPI - A name and a constraint (requests@^2.23.0) - A git url (git+https://github.com/python-poetry/poetry.git) - A git url with a revision (git+https://github.com/python-poetry/poetry.git#develop) - A file path (../my-package/my-package.whl) - A directory (../my-package/) - A url (https://example.com/packages/my-package-0.1.0.tar.gz) Package to add or search for (leave blank to skip):
Add the packages listed below one by one:
- mkdocs: The static site generator — required for this tutorial.
- mkdocs-material: An optional mkdocs extension which generates your site using Material Design.
- pymdown-extensions: An optional markdown plugin which adds a whole host of useful markdown extensions which we’ll configure later in this tutorial.
- fontawesome-markdown: An optional markdown plugin which adds native support for font-awesome glyphs directly within your markdown using the same syntax as emojis.
This command will create a new file called
pyproject.toml as shown:
cat pyproject.toml [tool.poetry] name = "docker" version = "0.1.0" description = "" authors = ["Ajeet Singh Raina <ajeetraina@Docker-Ajeet-Singh-Rainas-MacBook-Pro.local>"] readme = "README.md" [tool.poetry.dependencies] python = "^3.8" mkdocs = "^1.4.2" mkdocs-material = "^9.0.5" pymdown-extensions = "^9.9.1" fontawesome-markdown = "^0.2.6" [build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api"
poetry install command is used to install the dependencies of a Python project managed with Poetry. When you run “poetry install” in the terminal, Poetry will look for a
pyproject.toml file in the current directory and use the information in that file to install the specified dependencies for the project. The command will install the dependencies in the virtual environment created by Poetry for the project, so the dependencies will not conflict with other projects on your system.
By default, “poetry install” will install the dependencies in the ‘production’ environment, but you can also specify to install in the ‘development’ environment by running “poetry install –dev”
Additionally, If you have made changes to your dependencies, you can use the command “poetry update” to update the dependencies to the latest version that satisfies the constraints in your pyproject.toml file.
You will need to specify the version of Python.
cat runtime.txt 3.8
Create a new file called netlify.toml with the following entries:
publish = “site” command = “”” pip3 install -q poetry && poetry config virtualenvs.in-project true && poetry install -v && mkdocs build -d site “””
Run the below steps to push it to Github
git add . git commit -m "Added project" git push
Visit Netlify and ensure that the site gets built without any issue.
visit https://dockerlabs.netlify.app to access the site