Konso Wiki Demo

A modern wiki application for displaying Konso documentation, guides, and completed task summaries. The application features dynamic content from the Konso CMS API with a clean, responsive interface.

Features

• Dynamic Content Loading - Fetches wiki entries and categories from Konso CMS API
• Markdown Rendering - Converts markdown content to beautifully styled HTML
• Full-Text Search - Server-side search functionality with real-time results
• Responsive Design - Mobile-friendly three-panel layout
• Static + SSR Hybrid - Fast static pages with dynamic search

Tech Stack

• Framework: Astro v5.16.4 - Static site generation with hybrid SSR
• Styling: Tailwind CSS v4.1.17 - Utility-first CSS framework
• Markdown: marked v15 - GitHub Flavored Markdown parser
• Deployment: Node.js adapter for SSR pages
• Package Manager: pnpm v10.20.0

Prerequisites

• Node.js 18+ or 20+
• pnpm 10.20.0 (or npm/yarn)

Installation

Environment Variables

The application requires the following environment variables (defaults are provided):

Environment variables are configured in

Project Structure

wiki-demo/
├── src/
│   ├── components/
│   │   └── SideNav.astro          # Dynamic navigation component
│   ├── layouts/
│   │   └── BaseLayout.astro       # Main layout with header & sidebar
│   ├── lib/
│   │   └── konso.ts               # Konso API client functions
│   ├── models/
│   │   ├── CategoryDto.ts         # Category data model
│   │   ├── ContentDto.ts          # Content data model
│   │   └── MetaDataDto.ts         # Metadata model
│   ├── pages/
│   │   ├── index.astro            # Home page
│   │   ├── search.astro           # Search page (SSR)
│   │   └── wiki/
│   │       ├── [slug].astro       # Dynamic wiki entry pages
│   │       └── introduction.astro # Sample static page
│   └── styles/
│       └── global.css             # Global styles + markdown styling
├── astro.config.mjs               # Astro configuration
├── package.json                   # Dependencies
└── tailwind.config.mjs            # Tailwind configuration (removed in v4)

Architecture

Layout Structure

The application uses a three-panel layout:

1. Top Sticky Header - Fixed navigation bar with search functionality
2. Side Navigation Menu - Two-level hierarchy populated from Konso API:
   • First level: Categories
   • Second level: Individual wiki entries
3. Content Panel - Main area displaying markdown-rendered content

Data Flow

1. Build Time (Static Pages):

   • Categories fetched from Konso API
   • Wiki entries pre-fetched for all categories
   • Static HTML generated for each wiki entry via
     getStaticPaths()
   • Navigation structure built from API data

2. Request Time (Search Page):

   • Search page uses SSR (Server-Side Rendering)
   • Query parameters accessed at request time
   • Search results fetched from Konso API on-demand

API Integration

The application integrates with Konso CMS API through the following functions:

• fetchKonsoCategories()
  - Retrieves all categories
• fetchKonsoContent(type, category)
  - Fetches content by type and category
• searchKonsoContent(query, type)
  - Full-text search
• fetchKonsoContentBySlug(slug)
  - Retrieves specific content by slug
• fetchKonsoContentById(id)
  - Retrieves content by ID

Development

Adding New Pages

Static pages are auto-generated from the Konso API. To add custom pages:

1. Create
   .astro
   file in
   src/pages/
2. Import
   BaseLayout
   and
   SideNav
   components
3. Add content inside the layout

Styling Markdown Content

Markdown styling is defined in

• Headings (h1-h6)
• Links, lists, and blockquotes
• Code blocks and syntax highlighting
• Tables and images

Tailwind CSS 4.x

This project uses Tailwind CSS 4.x with:

• CSS-based configuration via
  @theme
  directive
• Native PostCSS integration (
  @tailwindcss/postcss
  )
• No
  tailwind.config.js
  file (v4 uses CSS config)
• Custom theme values in
  src/styles/global.css

Build & Deployment

Hybrid Output Mode

The project uses Astro's

• Most pages are pre-rendered as static HTML (wiki entries, home)
• Search page uses SSR for dynamic query parameter handling
• Requires Node.js environment for deployment

Build Command

Outputs to

• Static HTML files for wiki entries
• Server bundle for SSR pages
• Optimized CSS and assets

Running in Production

Or deploy to platforms supporting Node.js SSR (Vercel, Netlify, etc.)

Key Features Explained

Efficient Content Fetching

The dynamic route

• Fetch all content once at build time
• Generate static pages for each wiki entry
• Avoid duplicate API calls
• Pass content as props to avoid re-fetching

Search Functionality

Search page (

• Access query parameters at request time
• Fetch search results from Konso API dynamically
• Display results with title, category, excerpt, and link
• Handle errors gracefully

Markdown Rendering

Content from Konso API is:

• Parsed using
  marked
  library
• Rendered with GitHub Flavored Markdown support
• Styled with custom CSS classes
• Displayed with syntax highlighting for code blocks

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

ISC