Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity

feat(docs): restructure documentation with new framework and templates

Browse source 
- Archive old docs to docs-old/ for reference
- Create new top-down documentation structure:
  * Platform Overview: purpose, audience, product structure
  * Components: individual platform components (Forgejo, Kubernetes, Backstage)
  * Getting Started: onboarding and quick start guides
  * Operations: deployment, monitoring, troubleshooting
  * Governance: ADRs, project history, compliance
- Add DOCUMENTATION-GUIDE.md with writing guidelines and templates
- Add component template (TEMPLATE.md) for consistent documentation
- Simplify root README and move technical docs to doc/ folder
- Update test configuration:
  * Exclude legacy content from markdown linting
  * Relax HTML validation for theme-generated content
  * Skip link checking for legacy content in test:links
  * Keep 'task test' clean for technical writers (100% pass)
  * Add 'task test:full' with comprehensive link checking
- Update home page with corrected markdown syntax
- Fix internal links in archived content

BREAKING CHANGE: Documentation structure changed from flat to hierarchical top-down approach
This commit is contained in:
Stephan Lo 2025-11-16 13:32:10 +01:00
parent 2ec2efe9fc
commit 62999b41d0
196 changed files with 907 additions and 160 deletions
Download patch file Download diff file Expand all files Collapse all files

282
content/en/docs/documentation/quick-reference.md
View file

@ -1,282 +0,0 @@
---
title: "Quick Reference"
linkTitle: "Quick Reference"
weight: 60
description: >
Cheat sheet for common technicalWriter tasks.
---
## Common Commands
### Local Development
```bash
# Start development server (with hot reload)
task serve
# Build for production
task build
# Build for development (faster, no minification)
task build:dev
# Clean build artifacts
task clean
```
### Testing
```bash
# Quick tests (build + markdown)
task test:quick
# Full test suite
task test
# Individual tests
task test:build # Hugo build validation
task test:markdown # Markdown linting
task test:html # HTML validation
task test:links # Link checking
```
### Dependencies
```bash
# Install dependencies
task deps:install
# Update dependencies
task deps:update
# Ensure npm dependencies (auto-installs if missing)
task deps:ensure-npm
```
### Container Operations
```bash
# Build OCI/Docker image
task build:oci-image
# Build and test container
task test:oci-image
```
## File Locations
### Content
| Path | Description |
|------|-------------|
| `content/en/docs/` | Main documentation |
| `content/en/blog/` | Blog posts |
| `content/en/_index.md` | Homepage |
### Architecture Models
| Path | Description |
|------|-------------|
| `resources/edp-likec4/` | Platform architecture models |
| `resources/doc-likec4/` | Documentation platform models |
### Configuration
| File | Purpose |
|------|---------|
| `hugo.toml` | Hugo configuration |
| `config.yaml` | Docsy theme config |
| `Taskfile.yml` | Task definitions |
| `package.json` | npm dependencies and scripts |
| `.markdownlint.json` | Markdown linting rules |
| `.htmlvalidate.json` | HTML validation rules |
| `.htmltest.yml` | Link checker config |
### Build Output
| Path | Description |
|------|-------------|
| `public/` | Generated static site |
| `resources/_gen/` | Generated resources (Hugo) |
| `data/build_info.json` | Build metadata (git commit, version) |
## Markdown Frontmatter
### Standard Page
```yaml
---
title: "Page Title"
linkTitle: "Short Title"
weight: 10
description: >
Brief description for SEO and navigation.
---
```
### Blog Post
```yaml
---
title: "Post Title"
date: 2025-01-15
author: "Your Name"
description: >
Post summary.
---
```
## Embedding Architecture Diagrams
### Basic Embed
```markdown
{{< likec4-view view="view-name" project="project-name" >}}
```
### Parameters
- `view` (required) - The view ID from your LikeC4 model
- `project` (optional, default: "architecture") - The LikeC4 project name
- `title` (optional, default: "Architecture View: {view}") - Custom header text above the diagram
### Examples
```markdown
{{< likec4-view view="overview" project="documentation-platform" >}}
{{< likec4-view view="localDevelopment" project="documentation-platform" >}}
{{< likec4-view view="cicdPipeline" project="documentation-platform" >}}
{{< likec4-view view="otc-faas" project="architecture" title="OTC FaaS Deployment" >}}
```
## LikeC4 Commands
### Regenerate Webcomponents
After modifying `.c4` files:
```bash
task likec4:generate
```
This regenerates both:
- `static/js/likec4-webcomponent.js` (EDP architecture)
- `static/js/likec4-doc-webcomponent.js` (Documentation platform)
### Start Development Server
```bash
cd resources/doc-likec4 # or resources/edp-likec4
npm install
npm start
```
Opens LikeC4 IDE at `http://localhost:5173`
### Export Diagrams
```bash
cd resources/doc-likec4
npx likec4 export png -o ./images .
```
## Git Workflow
### Feature Branch
```bash
# Create feature branch
git checkout -b feature/your-feature
# Make changes and test
task serve
task test:quick
# Commit
git add .
git commit -m "Description of changes"
# Push
git push origin feature/your-feature
# Create pull request on GitHub
```
### Update from Main
```bash
git checkout main
git pull origin main
git checkout feature/your-feature
git rebase main
```
## Troubleshooting
### Port 1313 in use
```bash
lsof -ti:1313 | xargs kill -9
```
### Build errors
```bash
task clean
task build:dev
```
### Missing dependencies
```bash
task deps:install
```
### Hugo module issues
```bash
hugo mod clean
hugo mod get -u
hugo mod tidy
```
### LikeC4 language server
In VS Code: `Ctrl+Shift+P` → "LikeC4: restart language server"
## URLs
### Local Development
- **Documentation:** <http://localhost:1313>
- **LikeC4 IDE:** <http://localhost:5173> (when running `npm start` in likec4 folder)
### Production
Check `edgeconnectdeployment.yaml` for deployment URL or run:
```bash
kubectl get service edpdoc -n <namespace>
```
## Quick Checks Before Committing
1. ✅ `task test:quick` passes
2. ✅ Preview looks correct in browser
3. ✅ No broken links (visual check)
4. ✅ Architecture diagrams render
5. ✅ Frontmatter is correct
## Getting Help
- **Hugo docs:** <https://gohugo.io/documentation/>
- **Docsy theme:** <https://www.docsy.dev/docs/>
- **LikeC4:** <https://likec4.dev/>
- **Task:** <https://taskfile.dev/>
## View Documentation Architecture
To understand how this documentation platform works:
→ Start here: [Documentation About Documentation](../)