Markdown Generator

문서 분할 및 페이지 생성

이 도구는 하나의 큰 마크다운 문서를 여러 개의 파일로 분리하여 관리를 용이하게 합니다. 또한 문서를 두 개 이상의 페이지로 나누어 각 페이지별로 독립적인 콘텐츠를 유지할 수 있도록 지원합니다.

자동 목차 생성

마크다운 문서의 헤더 hierarchy(#를 h1, ##를 h2 등으로 인식)를 분석하여 자동으로 목차(table of contents)를 생성합니다. 생성된 목차는 문서 내 원하는 위치에 삽입할 수 있습니다.

기계 번역 지원

Microsoft Azure Translator API를 연동하여 문서 내용을 다양한 언어로 번역할 수 있습니다. 번역이 어려운 특정 텍스트에 대해서는 사용자 정의 번역 블록을 설정할 수 있으며, 번역 불가 영역을 지정하여 코드 블록이나 특수 서식을 원본 그대로 보존할 수 있습니다.

앵커 시스템

문서 내 특정 위치에 앵커를 설정하고, 다른 위치에서 해당 앵커를 참조하여 링크하거나 내용을 재사용할 수 있습니다. 이는 문서 내 교차 참조나 반복되는 내용을 효율적으로 관리하는 데 유용합니다.

수동 설치

1. 공식 GitHub 저장소에서 MarkdownGenerator.zip 파일을 다운로드합니다.
2. 다운로드한 ZIP 파일을 원하는 폴더에 압축 해제합니다.
3. 압축 해제된 폴더에서 MarkdownGenerator.exe 파일을 실행합니다.

Chocolatey를 통한 설치

Chocolatey 패키지 관리자가 설치된 경우, 다음 명령어를 실행하여 프로그램을 설치할 수 있습니다:
choco install markdown-generator
설치 후에는 다음 명령어로 업데이트가 가능합니다:
choco upgrade markdown-generator
필요 시 제거는 다음 명령어로 수행합니다:
choco uninstall markdown-generator

기본 사용법

명령 프롬프트에서 실행 파일을 호출하고 다음과 같은 인수를 전달하여 사용할 수 있습니다:

• --index-file: 문서 구조를 정의하는 XML 설정 파일의 이름을 지정합니다. 이 인수는 필수입니다.
• --base-dir: 출력 파일이 저장될 기본 디렉터리를 설정합니다. 지정하지 않으면 현재 디렉터리가 사용됩니다.
• --translator-key: Microsoft Azure Translator API 인증 키를 설정합니다. 지정하지 않으면 번역 기능이 비활성화됩니다.
• --verbose: 오류 발생 시 상세 메시지를 표시하려면 error 값을 지정합니다.
• help: 도움말 텍스트를 표시합니다.

인수의 순서는 유연하게 조정할 수 있으며, 다음과 같이 위치 기반으로도 사용할 수 있습니다:
MarkdownGenerator.exe "index.xml" "C:my-doc-folder" [api-key] --verbose error

실제 사용 예시

도움말 확인:
MarkdownGenerator.exe help

번역 및 인덱스 생성을 포함한 전체 기능 실행 예시:
MarkdownGenerator.exe --base-dir "C:my-doc-folder" --index-file "index.xml" --translator-key [api-key] --verbose error
여기서 [api-key]는 Microsoft Azure 포털에서 발급받은 Translator API 키로 대체해야 합니다. API 키 발급 및 서비스 설정 방법은 공식 문서에서 안내받을 수 있습니다.

지원 환경 및 시스템 요구사항

이 도구는 Windows 운영 체제에서만 실행됩니다. 공식 문서에서는 다른 운영 체제로의 포팅이 가능하다고 언급되지만, 현재 배포되는 버전은 Windows 전용 실행 파일로 제공됩니다. .NET 프레임워크가 설치된 환경이 필요할 수 있으나, 구체적인 버전 요구사항은 증거에 명시되지 않았습니다.

최신 버전 및 업데이트

현재 버전은 1.0.2이며, Chocolatey를 통해 choco upgrade markdown-generator 명령어로 최신 버전으로 업데이트할 수 있습니다. 업데이트 내역은 별도로 제공되지 않으므로, 최신 기능 및 변경 사항은 GitHub 저장소의リリース 페이지를 참조하는 것이 좋습니다.

제한 사항 및 확인 사항

이 도구는 GitHub의 마크다운 표준을 기반으로 설계되었기 때문에, 다른 마크다운 파서나 확장 문법을 사용하는 환경에서는 예상과 다르게 동작할 수 있습니다. 번역 과정에서 마크다운을 HTML로 변환하고, 번역 후 다시 마크다운으로 변환하는 과정이 포함되므로, 이 과정에서 원본 서식이 약간 변경될 수 있습니다. 또한, 복잡한 문서 구조에 대한 광범위한 테스트가 수행되지 않았으므로, 중요한 문서에서는 사전 검증이 권장됩니다.