G7 지식 문서 지원 템플릿 - Glitter Knowledge

개요

별도의 문서 CMS나 Knowledge 데이터베이스를 새로 만들지 않고, GnuBoard7의 게시판과 분류, 게시글을 그대로 활용합니다.

Board       → Topic
Category    → Collection
Post        → Document

기존 GnuBoard7 콘텐츠를 유지하면서 분류 → 검색 → 참조에 적합한 문서 중심의 사용자 경험을 제공하는 것을 목표로 합니다.

일반적인 커뮤니티나 블로그에서는 새로 올라온 글을 시간순으로 탐색하는 흐름이 중요합니다.

하지만 매뉴얼, 사용 가이드, FAQ, 기술 문서, 도움말 센터에서는 조금 다릅니다.

사용자는 보통 이런 질문을 가지고 들어옵니다.

“내가 필요한 정보가 어디 있지?”

Glitter Knowledge는 이 흐름에 맞춰 GnuBoard7의 기존 콘텐츠를 다음과 같이 재구성합니다.

GnuBoard7 Existing Content
        │
        ▼
Knowledge Content Adapter
        │
        ├── Topic Discovery
        ├── Collections
        ├── Document Search
        └── Document Reader

게시판은 Topic, 게시판의 분류는 Collection, 게시글은 Document로 표현됩니다.

예를 들어 GnuBoard7에서 다음과 같이 콘텐츠를 만들었다면,

게시판: 사용 가이드
│
├── 분류: 시작하기
│   ├── 설치 후 확인할 사항
│   └── 처음 시작하기
│
├── 분류: 사용법
│   ├── 게시판과 분류 사용하기
│   └── 기본 설정
│
└── 분류: FAQ
    └── 자주 묻는 질문

Glitter Knowledge에서는 다음과 같은 Knowledge 구조로 표현됩니다.

Topic: 사용 가이드
│
├── Collection: 시작하기
├── Collection: 사용법
└── Collection: FAQ
        │
        └── Document

별도의 Article이나 Document 테이블을 만들지 않습니다.

GnuBoard7과 sirsoft-board가 관리하는 기존 콘텐츠를 Knowledge 화면에 맞게 보여주는 Template Layer입니다.

---

Seed User Template

Glitter Knowledge는 완성된 문서 사이트를 그대로 제공하기 위한 Theme이 아니라, GnuBoard7에서 Knowledge / Documentation / Help Center 형태의 사이트를 시작하기 위한 Seed User Template입니다.

Topic, Collection, Document, Search, Document Reader, Authentication, Account 등 주요 기능 흐름은 실제 GnuBoard7과 sirsoft-board의 기능을 기반으로 구성되어 있습니다.

Board       → Topic
Category    → Collection
Post        → Document

현재 제공되는 Layout, Component, Typography, Color System과 Styling은 문서 사이트의 정보 구조와 기능 흐름을 갖춘 개발 출발점입니다.

특정 브랜드나 서비스에 맞춘 완성형 디자인을 제공하는 것을 목적으로 하지 않습니다.

실제 사이트에서는 이 Seed를 기반으로 프로젝트의 목적에 맞게 다음 요소들을 발전시킬 수 있습니다.

• Layout
• Component
• Typography
• Color System
• Visual Asset
• Branding
• 콘텐츠 구조

Glitter Knowledge의 핵심 가치는 완성된 디자인 자체보다 GnuBoard7의 기존 콘텐츠와 기능을 유지하면서 Knowledge 사이트 개발을 시작할 수 있는 구조와 구현 기반을 제공하는 것에 있습니다.

기존 GnuBoard7 콘텐츠를 문서 사이트처럼 사용할 수 있게 해주는 Seed User Template

---

주요 특징

Topic Discovery

Knowledge 첫 화면은 모든 문서를 한꺼번에 보여주기보다 어떤 주제의 지식이 있는지 발견하는 화면으로 구성했습니다.

공개된 GnuBoard7 게시판을 Topic으로 보여주며 사용자는 원하는 Topic을 선택해 해당 문서 영역으로 들어갑니다.

Knowledge
    │
    ▼
Topic Discovery
    │
    ├── 사용 가이드
    ├── 개발 문서
    ├── 운영 매뉴얼
    └── FAQ

Topic에는 게시판 설명과 함께 Document 수를 표시하여 어떤 종류의 지식이 구성되어 있는지 확인할 수 있습니다.

특정 게시판 ID나 slug를 Template에 고정하지 않기 때문에 사이트마다 자신의 콘텐츠 구조를 그대로 사용할 수 있습니다.

콘텐츠가 없는 경우에도 별도의 샘플 데이터를 강제로 만들지 않고 Empty State를 제공합니다.

---

Collection

Topic 안에서는 기존 게시판의 Category를 Collection으로 사용합니다.

Topic
  │
  ├── Collection A
  ├── Collection B
  └── Collection C

별도의 Collection 데이터베이스를 만들지 않습니다.

관리자가 기존 게시판에서 분류를 추가하거나 변경하면 Knowledge의 Collection 구조에도 그대로 반영됩니다.

Collection 화면에서는 같은 Topic에 속한 Collection을 함께 탐색할 수 있으며 현재 보고 있는 Collection을 구분하여 표시합니다.

Topic
  │
  ├── Collection A
  ├── Collection B  ← Current
  └── Collection C

각 Collection에서는 해당 분류에 속한 Document를 탐색하고 검색할 수 있습니다.

Document가 많아지는 경우 기존 sirsoft-board의 Pagination을 이용하여 페이지 단위로 탐색합니다.

존재하지 않는 Collection과 실제로 Document가 없는 Collection도 서로 다른 상태로 처리합니다.

---

Document Search

Topic을 선택하면 해당 Topic 안에서 필요한 Document를 검색할 수 있습니다.

검색 범위는 현재 선택한 게시판을 기준으로 하기 때문에 여러 Topic의 문서가 무분별하게 섞이지 않습니다.

Knowledge
   ↓
Topic
   ↓
Search
   ↓
Documents

첫 Discovery 화면에서는 검색보다 Topic 선택을 우선합니다.

즉,

Discover Topic
      ↓
Choose Scope
      ↓
Search Documents

의 흐름입니다.

Collection에서도 현재 Collection을 기준으로 Document를 검색할 수 있습니다.

검색 결과에서는 제목뿐 아니라 Collection, 본문 일부, 작성 시점 등 문서를 찾는 데 필요한 Context를 함께 제공합니다.

검색을 통해 Document로 이동하면 필요한 검색 Context를 Reader까지 전달합니다.

검색어가 없는 일반 탐색에서는 불필요한 빈 Query Parameter를 URL에 남기지 않습니다.

일반적인 Document URL은 다음과 같이 유지됩니다.

/knowledge/guide/documents/3

검색을 통해 접근한 경우에는 필요한 검색 Context가 전달될 수 있습니다.

/knowledge/guide/documents/4?q=검색어

---

Navigation Context

Glitter Knowledge는 단순히 화면을 연결하는 것뿐 아니라 사용자가 어떤 탐색 흐름을 통해 Document에 들어왔는지 유지하는 것을 중요하게 다룹니다.

Collection에서 Document를 열었다면 Reader에서도 해당 Collection을 확인할 수 있습니다.

Topic
  ↓
Collection
  ↓
Document
  ↓
Previous / Next

검색을 통해 Document를 찾았다면 검색 Context도 가능한 범위에서 유지합니다.

Topic
  ↓
Search
  ↓
Document
  ↓
Previous / Next

이를 통해 Document를 읽은 뒤 다시 탐색할 때 처음부터 탐색을 다시 시작하지 않아도 됩니다.

URL에는 실제 필요한 category와 q 값만 전달하며 값이 없는 경우 빈 Query Parameter를 생성하지 않습니다.

---

Document Reader

게시글 상세 화면은 일반적인 게시판 글 보기보다 문서를 읽고 참조하는 Reader 형태로 구성했습니다.

주요 기능은 다음과 같습니다.

• Topic / Collection / Document Breadcrumb
• Document 본문
• Collection Navigation
• Current Collection 표시
• Collection Context 유지
• Search Context 유지
• Previous / Next Document
• HTML Document Rendering
• Sanitized HTML
• Heading 기반 Table of Contents
• Current Section Tracking
• Section Deep Link
• Reading Progress
• Responsive Reader

Document를 읽는 동안 현재 Document가 어느 Topic과 Collection에 속해 있는지 확인할 수 있습니다.

Reader에서는 Collection Navigation을 제공하여 같은 Topic 안의 다른 Collection으로 이동할 수 있습니다.

Topic
│
├── 시작하기
├── 사용법       ← Current Collection
└── FAQ
        │
        ▼
     Document

현재 Collection은 Navigation에서 별도로 표시됩니다.

Document를 읽은 뒤에는 현재 Collection으로 돌아가거나 이전·다음 문서로 이동할 수 있습니다.

Collection이나 Search에서 Document로 들어온 경우 해당 Context를 가능한 범위에서 유지하여 탐색 흐름이 끊기지 않도록 구성했습니다.

---

Table of Contents

HTML 형식의 Document에 h2~h4 Heading이 존재하면 Reader에서 문서 목차를 구성할 수 있습니다.

Document
│
├── 시작하기
├── 설치
│   ├── 요구사항
│   └── 설정
└── 운영

Heading에는 안정적인 Anchor를 부여하여 문서 내부 Section으로 직접 이동할 수 있습니다.

긴 문서를 읽을 때 현재 어느 Section을 보고 있는지 쉽게 확인할 수 있도록 Current Section Tracking을 제공합니다.

문서를 스크롤하면 Reader가 현재 위치의 Heading을 추적하고 Table of Contents에서 해당 Section을 Current 상태로 표시합니다.

Table of Contents

시작하기
설치              ← Current Section
  요구사항
  설정
운영

현재 Section에는 접근성을 고려하여 다음 상태를 적용합니다.

aria-current="location"

TOC 항목을 선택하면 해당 Heading Anchor로 이동하며 URL Hash를 이용한 Section Deep Link도 지원합니다.

이 기능은 HTML Document의 실제 Heading 구조를 사용합니다.

---

Reading Progress

긴 Document를 읽을 때 현재 문서의 어느 정도까지 읽었는지 확인할 수 있도록 Reading Progress를 제공합니다.

Document Start
████████████░░░░░░░░
            ↑
      Current Position

문서를 스크롤하면 Reader의 진행 상태가 갱신됩니다.

Reading Progress와 Table of Contents를 함께 사용하면 장문 Document에서도 현재 읽고 있는 위치와 Section을 파악하기 쉽습니다.

Reading Progress는 콘텐츠 자체를 변경하지 않고 Reader Presentation Layer에서 동작합니다.

---

Text / HTML Content

GnuBoard7의 기존 게시글 Content Mode를 그대로 존중합니다.

Text Mode

일반 텍스트로 표시합니다.

HTML Mode

HTML을 Sanitizing한 후 렌더링합니다.

Heading이 존재하는 경우 다음 Reader 기능에 활용할 수 있습니다.

HTML Document
      ↓
Sanitized HTML
      ↓
Heading Detection
      ↓
Table of Contents
      ↓
Section Anchor
      ↓
Current Section Tracking

Text Mode의 내용을 Markdown으로 자동 변환하지 않습니다.

Markdown Parser를 Template에서 별도로 추가하지 않습니다.

---

콘텐츠 구조

Glitter Knowledge는 자체 Knowledge 데이터베이스를 만들지 않습니다.

Glitter Knowledge UI
        │
        ▼
Knowledge Content Adapter
        │
        ▼
GnuBoard7 / sirsoft-board
        │
        ▼
Existing Board Content

기본 매핑은 다음과 같습니다.

GnuBoard7	Glitter Knowledge
Board	Topic
Category	Collection
Post	Document

이 구조의 중요한 점은 콘텐츠의 소유권이 Template에 있지 않다는 것입니다.

Knowledge를 다른 User Template으로 변경하더라도 기존 게시판과 게시글은 그대로 남습니다.

Glitter Knowledge는 콘텐츠를 새로 소유하는 CMS가 아니라 기존 G7 콘텐츠를 지식·문서 사이트의 정보 구조로 표현합니다.

---

Authentication & Account

Glitter Knowledge는 별도의 회원 시스템을 만들지 않습니다.

GnuBoard7 Core가 제공하는 Authentication과 Account 기능을 사용하고 Knowledge에 맞는 화면을 제공합니다.

비회원에게는 다음 기능을 제공합니다.

• Login
• Register

로그인한 사용자에게는 Account Menu를 제공합니다.

Account
├── 계정
├── 관리자      (권한이 있는 경우)
├── 언어
└── 로그아웃

/account에서는 현재 GnuBoard7 계정 정보를 확인하고 수정할 수 있으며 비밀번호 변경도 Core의 기존 Account API를 사용합니다.

구조는 다음과 같습니다.

GnuBoard7 Core
    │
    ├── Authentication
    └── Account / Profile
             │
             ▼
       Glitter Knowledge
        Presentation

별도의 Authentication Backend나 Profile 데이터베이스를 만들지 않습니다.

---

디자인

Glitter Knowledge는 일반적인 게시판 화면보다는 문서를 찾고 오래 읽는 환경에 초점을 맞췄습니다.

화려한 Dashboard보다 정보 구조와 가독성을 우선합니다.

기본적인 Visual Direction은 다음과 같습니다.

• Documentation-first Layout
• 넓은 Reading Area
• 명확한 Topic / Collection Hierarchy
• Collection Navigation
• Current Collection State
• Reader Table of Contents
• Current Section State
• 절제된 Border와 Surface
• 읽기 중심 Typography
• Document Metadata
• Responsive Layout
• System / Light / Dark Color Scheme
• Keyboard Focus State
• 명확한 Link Recognition
• Accessible Current-state Navigation

Desktop에서는 Reader와 Navigation의 관계를 쉽게 파악할 수 있도록 구성하고, 작은 화면에서는 Single-column 흐름으로 전환합니다.

---

Light / Dark / System

다음 세 가지 Color Scheme을 제공합니다.

System
Light
Dark

System을 선택하면 운영체제의 Color Scheme을 따릅니다.

GnuBoard7에서 사용하는 공통 Color Scheme Preference와 연동하여 다른 지원 화면과 사용자 설정을 유지할 수 있도록 구성했습니다.

Knowledge의 Surface, Text, Border, Link, Focus State, Current Navigation 등은 Semantic Color Token을 기반으로 구성되어 Light와 Dark 환경에서 동일한 정보 구조를 유지합니다.

---

접근성

문서 탐색에서 현재 위치를 시각적으로만 구분하지 않도록 Semantic Navigation과 접근성 상태를 함께 사용합니다.

주요 적용 범위는 다음과 같습니다.

• 실제 Link와 Button의 Semantic Element 사용
• Search Form의 Label 연결
• Keyboard Focus State
• Collection Navigation의 aria-current
• Table of Contents의 Semantic Navigation
• Current Section의 aria-current="location"
• Breadcrumb Navigation
• Native Anchor Navigation
• Login / Register / Account Form Label
• Form Error State

Current Collection과 Current Section은 단순한 색상 변화에만 의존하지 않고 Navigation State로도 표현합니다.

---

Responsive

Desktop뿐 아니라 Tablet과 Mobile 환경에서도 Knowledge 구조를 유지하도록 구성했습니다.

Desktop
├── Header
├── Topic / Collection Navigation
└── Reader

Mobile
├── Compact Header
├── Collection Navigation
└── Single-column Reader

작은 화면에서는 여러 Column을 억지로 유지하지 않고 문서 읽기를 우선한 Single-column 흐름으로 전환합니다.

검색 Form, Collection Navigation, Reader Content, Previous / Next Navigation도 작은 화면에서 사용할 수 있도록 구성했습니다.

---

GnuBoard7 Integration

Glitter Knowledge는 기존 G7 확장 구조 안에서 동작합니다.

• GnuBoard7 Template Engine
• User Template
• JSON Layout
• React Component
• Template Routing
• Datasource / Action
• i18n
• sirsoft-board
• GnuBoard7 Core Authentication
• GnuBoard7 Core Account / Profile API
• Template Lifecycle
• Prebuilt Production Assets
• Light / Dark / System Color Scheme

별도의 Core 수정 없이 설치할 수 있습니다.

또한 sirsoft-page나 다른 User Template의 Account 화면에 의존하지 않습니다.

기능의 역할은 다음과 같이 나뉩니다.

GnuBoard7 Core
├── Authentication
├── Account
└── Permission

sirsoft-board
├── Board
├── Category
├── Post
├── Search
└── Navigation

Glitter Knowledge
├── Topic Presentation
├── Collection Presentation
├── Search UX
├── Document Reader
├── Table of Contents
├── Current Section Tracking
└── Knowledge Navigation

기존 G7 기능을 Template 내부에 다시 구현하기보다 기존 기능을 Knowledge UX에 맞게 연결하고 표현하는 것을 기본 원칙으로 합니다.

---

다국어

현재 다음 언어를 제공합니다.

• 한국어 (ko)
• 영어 (en)

Template의 고정 UI 문구는 Language Key로 관리합니다.

게시판 이름, 분류 이름, 문서 제목과 본문 등 실제 콘텐츠는 GnuBoard7에 저장된 원본 데이터를 사용합니다.

---

기술 스택

• GnuBoard7
• PHP 8.2+
• Laravel 12
• React
• TypeScript
• JSON Layout
• Vite
• sirsoft-board
• DOMPurify
• IntersectionObserver

Production CSS와 JavaScript가 Release Package에 포함되므로 일반적인 Template 설치를 위해 사용자가 별도로 Frontend Build를 수행할 필요는 없습니다.

---

현재 상태

Glitter Knowledge v0.13.0

현재 구현된 주요 범위는 다음과 같습니다.

• Topic Discovery
• Topic Document Count
• Collection Browsing
• Collection Sibling Navigation
• Current Collection State
• Document List
• Topic-scoped Search
• Collection-scoped Search
• Search Context Preservation
• Pagination
• Document Reader
• Reader Collection Navigation
• Previous / Next Document
• Collection Return Navigation
• HTML / Text Rendering
• Sanitized HTML
• Heading-based Table of Contents
• Current Section Tracking
• Section Deep Linking
• Reading Progress
• Login
• Registration
• Account / Profile
• Password Change
• Authenticated Account Menu
• Responsive UI
• System / Light / Dark Mode
• 한국어 / 영어
• G7 Template Lifecycle
• 독립 GitHub Repository
• ZIP / TAR.GZ Release Package

v0.13.0을 최초 공개 버전으로 배포합니다.

---

현재 제한사항

Glitter Knowledge는 문서 사이트를 위한 Presentation Template입니다.

따라서 다음과 같은 별도의 Backend 기능을 Template 안에 만들지 않습니다.

• 별도의 Knowledge Database
• 별도의 Document CRUD Backend
• 별도의 Authentication System
• 별도의 Permission System
• 독립 Search Engine
• Document Versioning
• Approval Workflow
• Collaboration System
• AI Search / RAG
• 별도의 WYSIWYG Editor
• 별도의 Collection Metadata Database
• 별도의 Related Document Engine

일반 사용자 게시글 작성 화면에서는 현재 GnuBoard7의 기본 작성 기능을 사용합니다.

Text Mode의 내용을 Markdown으로 자동 해석하지 않습니다.

HTML 기반 Table of Contents와 Current Section Tracking을 사용하려면 HTML Content에 h2~h4 Heading 구조가 있어야 합니다.

기능적인 요구가 커지는 영역은 Template에 계속 추가하기보다 별도의 G7 Module로 분리하는 것을 기본 방향으로 합니다.

---

이런 경우에 추천합니다

• 제품 사용 가이드를 만들고 싶은 경우
• 서비스 Help Center를 구성하려는 경우
• FAQ와 매뉴얼을 한곳에 정리하려는 경우
• 개발 문서나 기술 문서를 운영하려는 경우
• 사내 지식 베이스를 구성하려는 경우
• 기존 GnuBoard7 게시판 콘텐츠를 문서 형태로 보여주고 싶은 경우
• 별도의 Documentation CMS를 만들고 싶지 않은 경우
• Topic → Collection → Document 구조가 필요한 경우
• 긴 HTML 문서를 TOC와 함께 제공하려는 경우
• G7 기반 Knowledge / Documentation 사이트를 빠르게 시작하려는 경우

반대로 문서 승인 Workflow, Revision History, 공동 편집, AI Knowledge Search 같은 독립적인 Knowledge Management 기능이 필요한 경우에는 Template만으로 해결하기보다 별도의 Module과 함께 구성하는 것이 적합합니다.

---

프로젝트 방향

Glitter Knowledge의 목적은 GnuBoard7 안에 또 하나의 Knowledge CMS를 만드는 것이 아닙니다.

GnuBoard7에는 이미 게시판과 게시글, 분류, 회원, 권한 등의 기반 기능이 있습니다.

Glitter Knowledge는 그것을 다시 만들지 않고 다음과 같이 Knowledge UX로 재구성하는 역할에 집중합니다.

GnuBoard7
   │
   ├── Board
   ├── Category
   ├── Post
   ├── Authentication
   └── Permission
          │
          ▼
   Glitter Knowledge
          │
          ├── Topic
          ├── Collection
          └── Document

핵심은 간단합니다.

기존 GnuBoard7 콘텐츠를 문서 사이트처럼 사용할 수 있게 해주는 User Template

콘텐츠와 기능은 GnuBoard7에 남고, Glitter Knowledge는 그것을 찾기 쉽고, 분류하기 쉽고, 읽기 좋은 형태로 표현합니다.

---

요구사항

GnuBoard7

GnuBoard7 >= 7.0.11

PHP

PHP 8.2+

필수 확장

• 게시판 모듈 (sirsoft-board >= 1.1.2)

정확한 최소 버전은 Release의 template.json dependency 정의를 기준으로 합니다.

---

관리자에서 템플릿 설치

• 템플릿 ID: glitter-knowledge
• Template Type: User Template
• 현재 버전: v0.13.0
• 성격: Knowledge / Documentation / Help Center

1. GitHub 저장소에서 설치

관리자 → 템플릿 관리 → 수동 설치 → GitHub

아래 저장소를 사용합니다.

https://github.com/glitter-node/glitter-knowledge

설치가 완료되면 Glitter Knowledge를 활성화합니다.

2. ZIP 패키지 설치

GitHub Release에서 다음 패키지를 다운로드합니다.

• ZIP 템플릿 패키지를 다운로드

다운로드한 ZIP 패키지를 다음 경로에서 설치합니다.

관리자 → 템플릿 관리 → 수동 설치 → 파일 업로드

설치 완료 후 Glitter Knowledge 템플릿을 활성화합니다.

3. 처음 콘텐츠 구성하기

별도의 Knowledge 콘텐츠를 새로 만들 필요는 없습니다.

1. 게시판 생성
       ↓
2. 게시판을 Topic으로 사용
       ↓
3. 분류 생성
       ↓
4. 분류를 Collection으로 사용
       ↓
5. 게시글 작성
       ↓
6. 게시글을 Document로 사용

이후 Knowledge Home에서 Topic을 선택하여 문서를 탐색할 수 있습니다.

HTML Document에 h2~h4 Heading을 구성하면 Reader에서 Table of Contents와 Section Navigation을 활용할 수 있습니다.

4. 설치 후 화면 로드 오류가 발생하는 경우

관리자 → 환경설정 → 고급 → 캐시 모두 삭제

를 실행한 뒤 다시 확인합니다.

---

Repository / Release

GitHub

https://github.com/glitter-node/glitter-knowledge

Release

https://github.com/glitter-node/glitter-knowledge/releases/tag/v0.13.0

Release Packages

glitter-knowledge-v0.13.0.zip
glitter-knowledge-v0.13.0.tar.gz

---

라이선스

MIT License

Copyright © 2026 Glitter.kr