Static site Generator for Documentation and Blog free (open source) using MkDocs | Open-Source Documentation site generator and blog generator

{tocify} $title={Table of Contents}

Documentation that simply works


Write your documentation in Markdown and create a professional static site in minutes – searchable, customizable, for all devices.

Getting started

Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. If you're familiar with Python, you can install Material for MkDocs with pip, the Python package manager. If not, we recommend using docker.

Installation

Material for MkDocs is published as a Python package and can be installed with pip, ideally by using a virtual environment. Open up a terminal and install Material for MkDocs with:

pip install mkdocs-material


 This will automatically install compatible versions of all dependencies: MkDocs, Markdown, Pygments and Python Markdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.


Creating your site

After you've installed Material for MkDocs, you can bootstrap your project documentation using the mkdocs executable. Go to the directory where you want your project to be located and enter:

mkdocs new .

This will create the following structure:

 .

├─ docs/

│  └─ index.md

└─ mkdocs.yml

 



Configuration

Minimal configuration

Simply add the following lines to mkdocs.yml to enable the theme:

theme:

  name: material

Advanced configuration

Material for MkDocs comes with many configuration options. The setup section explains in great detail how to configure and customize colors, fonts, icons and much more:

  • Changing the colors
  • Changing the fonts
  • Changing the language
  • Changing the logo and icons
  • Ensuring data privacy
  • Setting up navigation
  • Setting up site search
  • Setting up site analytics
  • Setting up social cards
  • Setting up a blog
  • Setting up tags
  • Setting up versioning
  • Setting up the header
  • Setting up the footer
  • Adding a git repository
  • Adding a comment system
  • Building for offline usage
Furthermore, see the list of supported Markdown extensions that are natively integrated with Material for MkDocs, delivering an unprecedented low-effort technical writing experience.

Previewing as you write

MkDocs includes a live preview server, so you can preview your changes as you write your documentation. The server will automatically rebuild the site upon saving. Start it with:

mkdocs serve 
Point your browser to localhost:8000 and you should see:


Your Site with Material theme will look like below






Building your site

When you're finished editing, you can build a static site from your Markdown files with:

mkdocs build

 

Publishing your site

The great thing about hosting project documentation in a git repository is the ability to deploy it automatically when new changes are pushed. MkDocs makes this ridiculously simple.

GitHub Pages

If you're already hosting your code on GitHub, GitHub Pages is certainly the most convenient way to publish your project documentation. It's free of charge and pretty easy to set up.

with GitHub Actions

Using GitHub Actions you can automate the deployment of your project documentation. At the root of your repository, create a new GitHub Actions workflow, e.g. .github/workflows/ci.yml, and copy and paste the following contents:

name: ci 
on:
  push:
    branches:
      - master 
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

Now, when a new commit is pushed to either the master or main branches, the static site is automatically built and deployed. Push your changes to see the workflow in action.

If the GitHub Page doesn't show up after a few minutes, go to the settings of your repository and ensure that the publishing source branch for your GitHub Page is set to gh-pages.

Your documentation should shortly appear at <username>.github.io/<repository>.

with MkDocs

If you prefer to deploy your project documentation manually, you can just invoke the following command from the directory containing the mkdocs.yml file:


mkdocs gh-deploy --force

GitLab Pages


If you're hosting your code on GitLab, deploying to GitLab Pages can be done by using the GitLab CI task runner. At the root of your repository, create a task definition named .gitlab-ci.yml and copy and paste the following contents:


 image: python:latest

pages:

  stage: deploy

  script:

    - pip install mkdocs-material

    - mkdocs build --site-dir public

  artifacts:

    paths:

      - public

  rules:

    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Now, when a new commit is pushed to master, the static site is automatically built and deployed. Commit and push the file to your repository to see the workflow in action.

Your documentation should shortly appear at <username>.gitlab.io/<repository>.

Customization

Project documentation is as diverse as the projects themselves and Material for MkDocs is a great starting point for making it look beautiful. However, as you write your documentation, you may reach a point where small adjustments are necessary to preserve your brand's style.

Adding assets
MkDocs provides several ways to customize a theme. In order to make a few small tweaks to Material for MkDocs, you can just add CSS and JavaScript files to the docs directory.

Additional CSS
If you want to tweak some colors or change the spacing of certain elements, you can do this in a separate style sheet. The easiest way is by creating a new style sheet file in the docs directory:

.
├─ docs/
│  └─ stylesheets/
│     └─ extra.css
└─ mkdocs.yml
Then, add the following lines to mkdocs.yml:

extra_css:
  - stylesheets/extra.css

Setup and theme structure

Enable Material for MkDocs as usual in mkdocs.yml, and create a new folder for overrides which you then reference using the custom_dir setting:

theme:
  name: material
  custom_dir: overrides

Updated Content:


Add files as Markdown files inside the docs folder like below image:



Reference:




Thanks ✌👌

Post a Comment

Previous Post Next Post

postad

post ad 2