Blog/2025 05 20 test blog post (#51)
* Remove unused font-face definitions from stylesheets The `fonts.scss` file defining `Assistant` font-face rules has been deleted as it was no longer in use. This cleanup reduces unnecessary assets and improves maintainability. * Fix npm script command in blog preview workflow Replaced `npm scss:build` with the correct `npm run scss:build` command in the GitHub Actions workflow. This ensures the SCSS build step executes properly during site generation. * Update blog preview workflow to use mkdocs gh-deploy Replaces the GitHub Pages action with `mkdocs gh-deploy` for deploying previews. Simplifies the workflow configuration and reduces dependencies. * Update `site_url` logic and fix URL format consistency Simplified the `site_url` handling in the workflow by removing branch-specific URL construction. Additionally, ensured the main URL in `mkdocs.yml` uses a consistent trailing slash. This enhances clarity and maintains uniformity in URL formatting. * Set `use_directory_urls` in mkdocs.yml directly. Removed redundant script lines for configuring `use_directory_urls` in the workflow file. This simplifies deployment logic by directly defining the configuration in the mkdocs.yml file. * Remove unnecessary CSS source map file Deleted `custom.css.map` as it is not required for production. Removing it helps reduce clutter and keeps the repository clean. * Add support for 'satware.ai' as a homepage path Updated body-classes.js to treat 'satware.ai' as a homepage path by adding the 'home' class to the body element. This ensures correct behavior for both empty paths and specific developer GitHub Pages. * Simplify FAQ and navigation structure. Renamed `faq.md` to `index.md` for consistency and updated navigation links in `mkdocs.yml` to use folder paths directly. Adjusted `main.html` to clean up formatting with additional line breaks. * Update footer links to use relative paths Replaced absolute paths with relative paths for internal footer links to ensure consistency and improve maintainability. External links remain unchanged. * Fix relative URL for Jane Alesi's team page in authors file Updated the URL path for Jane Alesi to ensure correct navigation to her team page. This fixes a broken link caused by an incorrect relative URL. * Update footer links and enhance blog post on website relaunch Updated footer links to utilize dynamic `config.site_url` for consistent URL routing. Enhanced the blog post for better readability, showcasing the MkDocs implementation, GitHub integration, and use of Mermaid diagrams. * Update footer link and simplify satWay documentation Replaced the "Blog" link in the footer with "satWay Prinzipien" and refined the satWay documentation by removing overly detailed content about Jane Alesi. Additionally, added the Blog section to the site navigation in `mkdocs.yml`.
This commit is contained in:
@@ -0,0 +1,94 @@
|
||||
---
|
||||
date: 2025-05-20
|
||||
title: "Relaunch der satware.ai-Website mit MkDocs"
|
||||
description: "Ein ausführlicher Einblick in die technische Implementierung unseres Website-Relaunches mit MkDocs und die Integration von Mermaid-Diagrammen"
|
||||
authors: [michael-wegener]
|
||||
categories:
|
||||
- Entwicklung
|
||||
- Dokumentation
|
||||
tags:
|
||||
- MkDocs
|
||||
- GitHub
|
||||
- Mermaid
|
||||
- Workflow
|
||||
---
|
||||
|
||||
# Relaunch der satware.ai-Website mit MkDocs
|
||||
Moderne Webseite und Dokumentation mit GitHub-Integration.
|
||||
Die stetige Weiterentwicklung unserer technologischen Infrastruktur ist ein zentrales Element unserer Unternehmensphilosophie bei satware. In diesem Geist freuen wir uns, den Relaunch unserer Website satware.ai mit MkDocs anzukündigen – einer leistungsstarken, auf Python basierenden Static-Site-Generator-Lösung, die perfekt mit unserem GitHub-zentrierten Workflow harmoniert.
|
||||
|
||||
## Warum MkDocs? Technologische Vorteile im Überblick
|
||||
|
||||
MkDocs hat sich als die ideale Plattform für unsere Anforderungen erwiesen. Die Entscheidung für diese Technologie basiert auf mehreren technischen Vorteilen, die unseren Entwicklungsprozess optimieren:
|
||||
|
||||
- Markdown-basierte Inhalte: Schnelles und effizientes Content-Management mit der vertrauten Markdown-Syntax
|
||||
- Automatisierte Deployment-Pipeline: Nahtlose Integration mit GitHub Actions für kontinuierliche Aktualisierungen
|
||||
- Responsive Design: Optimale Darstellung auf allen Endgeräten durch moderne CSS-Frameworks
|
||||
- Erweiterbarkeit: Umfangreiche Plugin-Unterstützung für zusätzliche Funktionalitäten
|
||||
- Integrierte Suchfunktion: Leistungsstarke clientseitige Suche ohne Server-Komponenten
|
||||
- Mehrsprachige Unterstützung: Einfache Lokalisierung und Internationalisierung
|
||||
- Automatische Generierung von Inhalten durch unsere [KI-Agenten](../../team/index.md)
|
||||
|
||||
## Technische Implementation mit GitHub Pages
|
||||
|
||||
Der Relaunch basiert auf einer technisch ausgereiften Pipeline, die moderne DevOps-Praktiken implementiert. Unser Workflow nutzt die Leistungsfähigkeit von GitHub Actions für die automatisierte Generierung und Deployment der Website:
|
||||
|
||||
Die Grundlage bildet ein speziell konfigurierter GitHub-Workflow, der bei jeder Änderung im Repository automatisch ausgeführt wird.
|
||||
|
||||
|
||||
## Integration von Mermaid-Diagrammen
|
||||
|
||||
Ein besonderes Highlight unseres neuen Setups ist die native Integration von Mermaid-Diagrammen. Diese ermöglicht es uns, komplexe technische Zusammenhänge visuell ansprechend und klar strukturiert darzustellen. Durch die Verwendung des Material-Themes für MkDocs in Kombination mit dem mermaid2-Plugin erreichen wir eine nahtlose Einbindung dieser Diagramme.
|
||||
|
||||
Die Mermaid-Integration bietet folgende Vorteile:
|
||||
|
||||
- Codebasierte Diagramme: Versionierbar und leicht zu warten
|
||||
- Automatische Anpassung an das gewählte Farbschema (Light/Dark Mode)
|
||||
- Breite Unterstützung verschiedener Diagrammtypen: Flowcharts, Sequenzdiagramme, Klassendiagramme usw.
|
||||
- Responsive Darstellung auf allen Endgeräten
|
||||
|
||||
Hier ein Beispiel-Workflow, der unseren GitHub-basierten Deployment-Prozess visualisiert:
|
||||
|
||||
### Beispiel: GitHub-basierter MkDocs-Deployment-Workflow
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Lokales Repository] -->|git push| B[GitHub Repository]
|
||||
B -->|GitHub Action<br>Trigger| C[Build-Prozess]
|
||||
C -->|mkdocs build| D[Statische Webseite]
|
||||
D -->|Deployment| E[GitHub Pages]
|
||||
E -->|Veröffentlichung| F[satware.ai Website]
|
||||
```
|
||||
|
||||
### Projektstruktur
|
||||
|
||||
Die Struktur unseres MkDocs-Projekts mit Blog-Funktionalität ist wie folgt organisiert:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Projekt-Root] --> B[mkdocs.yml]
|
||||
A --> C[docs/]
|
||||
C --> D[blog/]
|
||||
D --> E[2025-05-20-relaunch-mit-mkdocs.md]
|
||||
D --> F[weitere-blogposts.md]
|
||||
C --> G[index.md]
|
||||
C --> H[assets/]
|
||||
H --> I[images/]
|
||||
H --> J[css/]
|
||||
A --> K[.github/]
|
||||
K --> L[workflows/]
|
||||
L --> M[deploy.yml]
|
||||
|
||||
```
|
||||
|
||||
## Vorteile des neuen Workflows für unser Entwicklerteam
|
||||
|
||||
Die Umstellung auf MkDocs bringt zahlreiche Vorteile für unser Entwicklungsteam:
|
||||
|
||||
- Vereinfachter Publishing-Prozess: Markdown-Dateien committen, pushen, und die Seite wird automatisch aktualisiert
|
||||
- Dezentrales Content-Management: Mehrere Teammitglieder können parallel am Content arbeiten
|
||||
- Pull-Request-basierte Überprüfung: Qualitätssicherung durch Reviews vor der Veröffentlichung
|
||||
- Automatisierte Tests: Möglichkeit, Markdown-Linting und andere Qualitätstests in den Workflow zu integrieren
|
||||
- Versionierte Dokumentation: Vollständige Änderungshistorie und Rollback-Möglichkeiten
|
||||
- Effiziente Kollaboration: Nutzung des gewohnten GitHub-Workflows für die Website-Entwicklung
|
||||
|
||||
Reference in New Issue
Block a user