목록으로 돌아갑니다

목차

2025-06-02
3 분

플랫 페이지 사용 문서

FlatPages는 Markdown 형식의 컨텐츠 쓰기를 지원하고 자동으로 디렉토리를 생성하며 미적 판독 인터페이스를 제공하는 간단하고 강력한 정적 페이지 관리 시스템입니다.

기능적 특징

  • 마크 다운 형식을 지원하여 컨텐츠를 작성합니다
  • 기사 카탈로그를 자동으로 생성합니다
  • 코드 강조 표시
  • 진행 지침을 읽으십시오
  • 반응 형 디자인, 모바일 지원
  • 기사 탐색 지원 (이전/Next)
  • 기사 검색 지원
  • 국제 지원

사용 방법

1. 구성 활성화

구성 파일에서 플랫 페이지를 활성화합니다.

[flatpages] 
    # 是否启用flatpages 
    enable = true 
    # 支持配置多个flatpage目录 
    [[flatpages.dirs]] 
        nav_name = "帮助文档" 
        nav_path = "docs" 
        file_path = "statics/flatpages/docs" 
        # 每页显示的条目数，可选，默认为10 
        page_size = 20 
 
    # 可以继续添加更多目录配置... 

2. 기사를 만듭니다

statics/flatpages 디렉토리에서 .md 파일을 작성하고 다음 형식으로 작성하십시오.

# 文章标题 
 
> 文章描述（会显示在列表页） 
 
正文内容... 
 
## 二级标题 
 
### 三级标题 
 
正文内容... 

3. 마크 다운 형식 설명

Flatpages는 다음을 포함하여 표준 Markdown 구문을 지원합니다.

  • 제목 (H1-H4)
  • 목록 (주문 및 변수)
  • 코드 블록 (구문 강조 표시)
  • 참조 블록
  • 링크
  • 그림
  • 인라인 코드

코드 블록 예 :

def hello(): 
    print("Hello, World!") 

4. 특별 기능

코드 사본

복사 버튼은 모든 코드 블록의 오른쪽 상단에 자동으로 추가되어 사용자가 코드를 복사 할 수 있도록합니다.

디렉토리 탐색

이 시스템은 기사 제목 (H2-H4)을 기반으로 디렉토리를 자동으로 생성하고 오른쪽에 표시합니다. 디렉토리 지원 :

  • 현재 읽기 위치를 자동으로 강조 표시합니다
  • 점프하려면 클릭하십시오
  • 동기화를 스크롤하십시오

읽기 진행

페이지 상단에 읽기 진행률 표시 줄이 표시되며, 이는 읽기 위치가 시각적으로 표시됩니다.

구현 원리

1. 파일 시스템

FlatPages는 GO의 embed.FS 사용하여 정적 파일을 관리합니다.

//go:embed flatpages/* 
var Files embed.FS 

2. 라우팅 등록

시스템은 시작시 InitFlatpages 함수를 통해 관련 경로를 등록합니다.

  • /fp/ - 기사 목록 페이지
  • /fp/:slug - 기사 세부 정보 페이지

3. 마크 다운 분석

Markdown 파싱, 지원을 위해 gomarkdown/markdown 패키지를 사용하십시오.

  • commonextensions
  • 자동 헤드 링 시드
  • HreftArgetBlank

4. 기사 관리

모든 Markdown 파일은 시작시로드됩니다.

  1. 파일 이름을 URL 슬러그로 해결하십시오
  2. 기사 제목 (H1) 추출
  3. 기사 설명 추출 (첫 번째 인용 블록)
  4. 읽기 시간을 계산하십시오
  5. 기록 업데이트 시간

5. 검색 구현

목록 페이지의 검색 기능은 제목 및 설명의 실시간 검색을 지원하는 JavaScript에서 구현됩니다.

6. 국제 지원

이 시스템은 i18N 지원을 통합하며 구성을 통해 다국어 지원을 활성화 할 수 있습니다.

[i18n] 
enable = true 

모범 사례

  1. 파일 이름 지정
    • 의미있는 파일 이름을 사용하여 URL의 일부로 사용됩니다.
    • 특수 캐릭터와 공간을 피하십시오
    • 소문자와 하이픈이 권장됩니다
  2. 콘텐츠 조직
    • 각 파일에는 H1 제목이 있어야합니다
    • 인용 블록을 사용하여 기사 설명을 추가하십시오
    • 컨텐츠를 구성하기 위해 2 차 및 3 차 타이틀을 합리적으로 사용하십시오
    • 단일 파일의 크기를 제어하면 1000 줄을 초과하지 않는 것이 좋습니다.
  3. 이미지 처리
    • 사진은 statics/img 디렉토리에 저장하는 것이 좋습니다.
    • 상대 경로를 사용한 참조 이미지
    • 이미지를 압축하여 로딩 속도를 높입니다
  4. 코드 디스플레이
    • 올바른 구문 강조 표시를 얻으려면 코드 블록의 언어를 지정하십시오.
    • 중요한 코드에 주석을 추가하십시오
    • 코드 블록이 올바르게 들여 쓰기되었는지 확인하십시오

문제 해결

  1. 페이지가 표시되지 않습니다
    • flatpages.enable 이 구성 파일에서 true인지 확인하십시오
    • 마크 다운 파일이 올바른 디렉토리에 있는지 확인
  2. 디렉토리가 생성되지 않았습니다
    • 기사에 2 차 또는 3 차 제목이 포함되어 있는지 확인
    • 제목이 올바른지 확인하십시오 (## 또는 ###)
  3. 스타일 예외
    • Markdown Syntax가 올바른지 확인하십시오
    • 파일 인코딩이 UTF-8인지 확인하십시오
  4. 잘못된 검색
    • 브라우저 콘솔에서 JavaScript 오류를 확인하십시오
    • 페이지 JavaScript가 올바르게로드되는지 확인하십시오
목록으로 돌아갑니다