search

sentenz / convention

General articles, conventions, and guides.
https://sentenz.github.io/convention/
Apache License 2.0
4 stars 2 forks source link

Modify article about `Static Site Generators (SSG)` #314

Closed sentenz closed 6 months ago

sentenz commented 6 months ago

Static Site Generators (SSG)

Static Site Generators (SSG) are tools used to create static websites by generating HTML, CSS, and JavaScript files during a build process.

1. Category

1.1. MkDocs

MkDocs is a fast, simple, and beautiful static site generator geared towards building project documentation. It uses Markdown for documentation source files and a single YAML configuration file for setup. MkDocs comes with a selection of themes and allows for extensive customization. It includes a built-in dev server that auto-reloads to show changes in real-time. MkDocs generated sites are completely static and can be hosted on static web hosting services such as GitHub Pages or Amazon S3.

1.1.1. Hoster

1.1.1.1. GitLab

  1. Files and Folders

    • Project Layout

      Directory structure of a Pages project. The /docs directory contains all markdown files that will be converted into HTML pages.

      ├── /docs
│   ├── /adr
│   │   ├── merging-strategy-adr.md
│   │   └── branching-strategy-adr.md
│   ├── api.md
│   └── README.md

    • mkdocs.yml

      The mkdocs.yml file is the configuration file for MkDocs.

      NOTE The defauft value for site_dir is site and for docs_dir is docs, modify the values as needed.

      site_name: <Project>
site_description: <Description of Project.>
repo_url: <repository>
repo_name: GitLab
docs_dir: docs
site_dir: public

nav:
- Home: README.md
- ADR:
  - Merging Strategy: adr/merging-strategy-adr.md
  - Branching Strategy: adr/branching-strategy-adr.md
- API: api.md

    • ./gitlab/pages.yml

      Configure GitLab CI by creating a .gitlab/pages.yml file to set up CI/CD pipelines for automatic deployment.

      NOTE GitLab Pages uses the /public directory to serve the static site. GitLab CI will automatically build and deploy the site to GitLab Pages.

      ---
spec:
inputs:
  stage:
    default: pages
  job:
    default: pages
  image:
    default: python:latest
  tags:
    default: devops
  artifacts:
    default: "public"
  script:
    default: |
      pip install mkdocs mkdocs-material mkdocs-macros-plugin pymdown-extensions
      mkdocs build
---
"$[[ inputs.job ]]":
stage: $[[ inputs.stage ]]
image: $[[ inputs.image ]]
rules:
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
tags:
  - $[[ inputs.tags ]]
script: $[[ inputs.script ]]
artifacts:
  name: "$CI_JOB_NAME"
  paths:
    - $[[ inputs.artifacts ]]

    • .gitlab-ci.yml

      Modify the GitLab CI file in the root of the /project directory to configure the CI/CD pipeline for automatic deployment.

      ---
include:
- local: ".gitlab/pages.yml"
 inputs:
   stage: deploy

  2. Command and Operations

    • Install

      Installs MkDocs on the GitLab CI runner along with a set of extensions and themes, such as Material for MkDocs, which provides a material design theme, and various plugins and extensions to enhance the documentation.

      pip install mkdocs mkdocs-material mkdocs-macros-plugin pymdown-extensions

    • Setup

      Initializes a new MkDocs project in the current directory. It creates a default mkdocs.yml configuration file and a /docs directory for documentation source files.

      mkdocs new .

    • Build

      Builds the MkDocs site by converting the markdown files in the /docs directory into HTML pages and assets in the site_dir directory.

      NOTE GitLab Pages uses the /public directory to serve the static site. MkDocs will automatically build and deploy sites located in /public to GitLab Pages.

      mkdocs build
1.1.1.2. GitHub

  1. Files and Folders

    • Project Layout

      Directory structure of a Pages project. The /docs directory contains all markdown files that will be converted into HTML pages.

      ├── /docs
│   ├── /adr
│   │   ├── merging-strategy-adr.md
│   │   └── branching-strategy-adr.md
│   ├── api.md
│   └── README.md

    • mkdocs.yml

      The mkdocs.yml file is the configuration file for MkDocs.

      NOTE The defauft value for site_dir is site and for docs_dir is docs, modify the values as needed.

      site_name: <Project>
site_url: https://<repository>.github.io/<project>/
site_author: <Author>
site_description: <Description of Project.>
repo_url: https://github.com/<repository>/<project>/
repo_name: GitHub
edit_uri: blob/main/docs/
docs_dir: docs
site_dir: public

nav:
- Home: README.md
- ADR:
  - Merging Strategy: adr/merging-strategy-adr.md
  - Branching Strategy: adr/branching-strategy-adr.md
- API: api.md

    • .github/workflows/pages.yml

      Create a .github/workflows/pages.yml file to set up GitHub Actions for automatic deployment. Ensure that the actions/upload-pages-artifact point to the site_dir directory from the mkdocs.yml configuration file.

      NOTE Enable GitHub Pages under the repository settings and select the gh-pages branch as the source. GitHub Actions will automatically build and deploy the site to the gh-pages branch.

      ---
name: Pages
on:
push:
  branches:
    - main
permissions:
contents: write
id-token: write
pages: write
jobs:
pages:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: 3.x
    - name: Workflow
      run: |
      pip install mkdocs mkdocs-material mkdocs-macros-plugin pymdown-extensions
      mkdocs build
    - name: Upload
      uses: actions/upload-pages-artifact@v3
      with:
        path: public
    - name: Deploy
      uses: actions/deploy-pages@v4

  2. Command and Operations

    • Install

      Installs MkDocs on the GitHub Actions along with a set of extensions and themes, such as Material for MkDocs, which provides a material design theme, and various plugins and extensions to enhance the documentation.

      pip install mkdocs mkdocs-material mkdocs-macros-plugin pymdown-extensions

    • Setup

      Initializes a new MkDocs project in the current directory. It creates a default mkdocs.yml configuration file and a /docs directory for documentation source files.

      mkdocs new .

    • Build

      Builds the MkDocs site by converting the markdown files in the /docs directory into HTML pages and assets in the site_dir directory.

      NOTE GitLab Pages uses the /public directory to serve the static site. MkDocs will automatically build and deploy sites located in /public to GitLab Pages.

      mkdocs build

2. Terminology

3. References

github-actions[bot] commented 1 week ago

:tada: This issue has been resolved in version 2.1.0 :tada:

The release is available on:

Your semantic-release bot :package::rocket: