{"id":25726927,"url":"https://github.com/fblettner/fblettner.github.io","last_synced_at":"2026-01-28T11:03:39.766Z","repository":{"id":206429400,"uuid":"466575113","full_name":"fblettner/fblettner.github.io","owner":"fblettner","description":"Knowledge Base for NOMANA-IT","archived":false,"fork":false,"pushed_at":"2025-05-16T10:09:36.000Z","size":22402,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-14T19:24:28.878Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fblettner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-03-05T21:48:32.000Z","updated_at":"2025-05-16T10:09:16.000Z","dependencies_parsed_at":"2025-06-01T18:38:07.824Z","dependency_job_id":"f8ec7ef7-1104-4a82-bb55-73484e2aea1a","html_url":"https://github.com/fblettner/fblettner.github.io","commit_stats":null,"previous_names":["fblettner/fblettner.github.io"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fblettner/fblettner.github.io","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fblettner%2Ffblettner.github.io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fblettner%2Ffblettner.github.io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fblettner%2Ffblettner.github.io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fblettner%2Ffblettner.github.io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fblettner","download_url":"https://codeload.github.com/fblettner/fblettner.github.io/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fblettner%2Ffblettner.github.io/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28844440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T10:53:21.605Z","status":"ssl_error","status_checked_at":"2026-01-28T10:53:20.789Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-25T23:27:54.178Z","updated_at":"2026-01-28T11:03:39.739Z","avatar_url":"https://github.com/fblettner.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Installing and Deploying MkDocs Material with GitHub Pages\n\nThis guide explains how to install and deploy MkDocs Material for creating beautiful documentation sites. It also includes steps to automate deployment to GitHub Pages.\n\n### What's Included in the Site\n\nThe provided MkDocs Material configuration is designed to support a comprehensive documentation site with the following features:\n\n- **Navigation**:\n    * Multi-level navigation with tabs and collapsible sections.\n    * Support for documentation, guides, blog posts, API references, and release notes.\n\n- **Customization**:\n    * Custom logo and favicon.\n    * Light and dark themes with a toggle switch.\n    * Customizable color palettes to match your branding.\n\n- **Enhanced User Experience**:\n    - Instant navigation with prefetching for fast transitions.\n    - Sticky top navigation for ease of access.\n    - Copy button for code snippets to improve developer productivity.\n\n- **Plugins**:\n    - `awesome-pages`: Automatically organizes navigation based on folder structure.\n    - `minify`: Optimizes site assets for faster loading.\n    - `blog`: Supports structured and visually appealing blog posts.\n    - `search`: Integrated full-text search for quick access to content.\n\n- **Content Types**:\n    - Documentation sections for getting started, installation guides, and tutorials.\n    - Blog posts with structured navigation and metadata.\n\n- **Technical Enhancements**:\n    - Cookie consent settings to comply with privacy policies.\n    - CSP (Content Security Policy) meta tag for enhanced security.\n    - Custom CSS and JavaScript to further tailor the site's appearance and functionality.\n\n### Repository Features\n\nThe repository includes:\n\n1. A complete `mkdocs.yml` configuration with navigation, theme, and plugin settings.\n2. A `docs/` directory with pre-structured files and folders for easy customization.\n3. Workflow configuration (`.github/workflows/deploy.yml`) to automate deployment to GitHub Pages.\n4. Sample blog posts, API documentation, and guides to demonstrate how to structure content.\n5. Custom assets for branding, including a logo and favicon.\n\nBy cloning this repository, you can start with a fully functional MkDocs Material site and focus on adding your content instead of setting up the structure.\n\n## Step 1: Prerequisites\n\nBefore starting, ensure you have the following:\n- **Python 3.x** installed (verify with `python --version`).\n  \n- **pip** installed (verify with `pip --version`).\n  \n- A **GitHub repository** to host your documentation.\n  \n- Git configured locally with a GitHub personal access token if needed.\n\n\n## Step 2: Install MkDocs Material\n\n1. **Create a Virtual Environment** (optional but recommended):\n   ```bash\n   python -m venv venv\n   source venv/bin/activate # On Windows, use venv\\Scripts\\activate\n   ```\n\n2. **Install MkDocs Material**:\n   ```bash\n   pip install mkdocs-material\n   ```\n\n3. **Verify Installation**:\n   ```bash\n   mkdocs --version\n   ```\n\n---\n\n## Step 3: Create the MkDocs Project\n\n1. **Create a New MkDocs Project**:\n   ```bash\n   mkdocs new my-project\n   cd my-project\n   ```\n\n2. **Edit the `mkdocs.yml` File**:\n   Replace the default configuration with the following:\n\n   ```yaml\n   site_name: Your Site Name\n   site_url: Your Site URL\n\n   theme:\n     name: material\n     logo: assets/your_logo.png\n     favicon: assets/your_logo.png\n     custom_dir: overrides\n     palette:\n       - media: \"(prefers-color-scheme: light)\"\n         primary: blue grey\n         accent: amber\n         scheme: default\n         toggle:\n           icon: material/weather-night\n           name: Switch to dark mode\n       - media: \"(prefers-color-scheme: dark)\"\n         primary: blue grey\n         accent: amber\n         scheme: slate\n         toggle:\n           icon: material/weather-sunny\n           name: Switch to light mode   \n     features:\n       - content.code.copy     \n       - navigation.instant\n       - navigation.tabs\n       - navigation.path\n       - navigation.top\n       - navigation.footer\n       - header.autohide\n\n   # example of navigation\n   nav:\n     - Home: index.md\n     - Liberty:\n         - Getting Started: liberty/getting-started.md\n         - Installation:\n           - Architecture: liberty/technical/architecture.md\n           - Docker Installation Guide: liberty/technical/installation.md\n           - Installation Tools Deployment Guide: liberty/technical/tools-deployment.md\n           - Liberty Deployment Guide: liberty/technical/liberty-deployment.md\n           - Create Linux Services: liberty/technical/linux-services.md\n           - Enable SSL with Traefik: liberty/technical/post-ssl.md    \n     - Blog:\n       - blog/index.md\n\n   plugins:\n     - search\n     - awesome-pages\n     - minify\n     - blog\n\n   extra:\n     social:\n       - icon: fontawesome/brands/github\n         link: your social link for github\n       - icon: fontawesome/brands/linkedin\n         link: your social link for linkedin          \n     meta:\n         - name: Content-Security-Policy\n           value: frame-ancestors 'self' https://giscus.app;      \n     consent:\n       title: Cookie consent\n       actions:\n         - accept\n         - manage\n         - reject\n       description: \u003e- \n         We use cookies to recognize your repeated visits and preferences,\n         as well as to measure the effectiveness of our documentation.\n     markdown_extensions:\n       - attr_list\n       - pymdownx.highlight:\n           anchor_linenums: true\n           linenums: true\n           line_spans: __span\n           pygments_lang_class: true\n       - pymdownx.inlinehilite\n       - pymdownx.snippets\n       - pymdownx.superfences\n   extra_css:\n     - css/custom.css\n   extra_javascript:\n     - js/extra.js  \n   copyright: \u003e\n     Copyright \u0026copy; 2024 Nomana-IT –\n     \u003ca href=\"#__consent\"\u003eChange cookie settings\u003c/a\u003e\n   ```\n\n3. **Add Your Documentation Files**:\n   Organize your files under the `docs/` folder as per the navigation structure defined in the `mkdocs.yml`.\n\n---\n\n## Step 4: Deploy to GitHub Pages\n\n1. **Set Up GitHub Actions**:\n   Add the following configuration in `.github/workflows/deploy.yml`:\n\n   ```yaml\n   name: ci \n   on:\n     push:\n       branches:\n         - master \n         - main\n   permissions:\n     contents: write\n   jobs:\n     deploy:\n       runs-on: ubuntu-latest\n       steps:\n         - uses: actions/checkout@v4\n         - name: Configure Git Credentials\n           run: |\n             git config user.name github-actions[bot]\n             git config user.email 41898282+github-actions[bot]@users.noreply.github.com\n         - uses: actions/setup-python@v5\n           with:\n             python-version: 3.x\n         - run: echo \"cache_id=$(date --utc '+%V')\" \u003e\u003e $GITHUB_ENV \n         - uses: actions/cache@v4\n           with:\n             key: mkdocs-material-${{ env.cache_id }}\n             path: .cache\n             restore-keys: |\n               mkdocs-material-\n         - run: pip install mkdocs-material mkdocs-awesome-pages-plugin mkdocs-minify-plugin\n         - run: mkdocs gh-deploy --force\n   ```\n\n2. **Push Your Changes**:\n   Commit and push your project to the `main` branch of your GitHub repository:\n   ```bash\n   git add .\n   git commit -m \"Initial documentation setup\"\n   git push origin main\n   ```\n\n3. **Access Your Site**:\n   After GitHub Actions finish deploying, your site will be live at:\n   ```\n   https://\u003cyour-github-username\u003e.github.io/\u003crepository-name\u003e/\n   ```\n\n---\n\n## Conclusion\n\nYour MkDocs Material documentation is now installed and deployed with GitHub Pages! This workflow ensures automated deployment and a professional look for your documentation site.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffblettner%2Ffblettner.github.io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffblettner%2Ffblettner.github.io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffblettner%2Ffblettner.github.io/lists"}