MKDocs와 함께 제품 문서 구축

“제품이 문서만큼 좋다”는 인기있는 최대 값이 있습니다. 이것은 물리적 제품과 마찬가지로 소프트웨어의 경우에도 적용됩니다.

프론트 엔드 디자인을 전문으로하지 않는 소규모 인디 개발자로서, 나는 종종 프리랜서를 고용하여 제품 웹 사이트를 구축합니다. 물론 문서 섹션이 포함됩니다.

문서 섹션은 간단한 제품을 위해서도 구축하는 데 약간의 시간과 돈이 걸릴 수 있으므로 모든 사이트에 대해 휠을 재발 명하지 않아도됩니다. 다행히도 방법이 있습니다.

키 테이크 아웃

mkdocs는 프로젝트 문서를 구축하는 데 이상적인 무료 정적 사이트 생성기입니다. 가볍고 호스팅하기 쉽고 독립형 사이트 또는 더 큰 사이트의 문서 섹션에 사용할 수 있습니다. MKDocs를 사용하려면 Python 및 PIP (Python 패키지 관리자)를 컴퓨터에 설치해야합니다. MKDocs는 컴퓨터에 로컬로 설치되어 오프라인으로 문서를 구축 할 수 있습니다. MKDOCS는 다양한 테마와 MKDOCS.YML 구성 파일을 통해 새 페이지를 추가 할 수있는 기능을 사용하여 사용자 정의 할 수 있습니다. 또한 문서의 로컬 미리보기를위한 내장 웹 서버도 포함되어 있습니다. MKDocs와 함께 구축 된 문서는 GitHub 페이지와 같은 서비스에서 무료로 호스팅 될 수 있으며 문서 또는 자신의 서버에서 읽을 수 있습니다. MKDocs는 또한이 플랫폼에 직접 배포를 지원합니다

mkdocs 소개 mkdocs는 프로젝트 문서 구축을위한 무료 정적 사이트 생성기입니다. 독립형 사이트 또는 더 큰 사이트의 문서 섹션 만 생성하는 데 사용될 수 있습니다. mkdocs는 정적 파일을 생성하기 때문에 문서는 가벼운 가중치이며 호스트하기 쉽습니다. Github 페이지와 같은 무료 서비스를 사용하고 문서를 읽거나 자체 서버에서 읽습니다. 이 기사에서는 MKDocs를 소개하여 설치 방법을 보여주고 문서를 작성하고 웹 서버에서 생성 된 문서를 주최합니다. mkdocs가 제작 한 문서의 감각을 얻으려면 Docs 테마 읽기를 사용하여 MKDocs로 구축 된 프로파일 렙레이스 WordPress 플러그인 문서를 살펴보십시오. mkdocs는 파이썬으로 작성되었습니다. 문서 소스 파일은 Markdown으로 작성되었으며 단일 YAML 구성 파일로 구성됩니다. MKDocs로 문서를 작성하려면 컴퓨터에 로컬로 설치해야합니다. 다음으로 설치 방법을 살펴 보겠습니다 Python 및 mkdocs 설치 Jekyll과 같은 정적 사이트 생성기 (주로 블로그에 사용되고 루비를 기반으로 함) 및 MKDoc은 일부 명령 줄을 필요로하므로 경고해야합니다. 그러나 명령 줄을 사용하는 데 익숙하지 않은 사람들에게는 보이지 않기 때문에 읽고 시도해 보는 것이 좋습니다! Python 및 PIP 설치 MKDoc을 설치하려면 컴퓨터에 Python 및 Pip (Python 패키지 관리자)가 설치되어 있어야합니다. 컴퓨터에 이미 설치 될 수 있습니다. Python 3.4 이상이 설치된 경우 PIP가 설치되었을 수 있습니다. (전체 지침은 Python 설치 안내서를 참조하십시오.) Ubuntu와 같은 Linux 배포에 Python을 설치하려면이 stackoverflow 스레드를 참조하거나 배포를 Google 검색하십시오. Windows의 경우 선호하는 버전 설치 프로그램을 다운로드하고 파일을 실행하여 Python을 설치하십시오. 또는 기계에 초콜릿 패키지 관리자가 설치되어 있으면 Choco 설치 파이썬을 실행하십시오. 파이썬 분배가 PIP가 설치되어 있는지 확인하려면 PIP -Version 명령을 실행하십시오. 그렇지 않으면 초콜릿을 통해 Python get-pip.py 또는 Choco를 설치하여 설치하십시오. mkdocs 설치 이제 파이썬과 PIP가 설치되었으므로 MKDOC를 설치하기 위해 MKDOC를 설치하는 PIP를 실행하십시오. 모든 것이 괜찮은지 확인하려면 MKDocs가 MKDOCS 명령을 내리는 데 도움이됩니다. Windows에 있고 MKDocs 명령이 살아 있지 않은 경우 C : Path-to-Python-Folderscripts를 경로 환경 변수에 추가하십시오. 문서 구축 이제 Python과 MKDocs가 설정되어 있으므로 실제 문서를 사용할 수 있습니다. 먼저, 문서에 대한 프로젝트를 만들고 (SP-DOC라고 부르겠습니다) 생성 된 폴더로 이동하십시오 :

생성 된 프로젝트 폴더에는 문서의 Markdown 파일이 저장 될 Docs 폴더와 구성 파일 MKDOCS.YML. 가 포함됩니다. 여기에 디렉토리 구조는 다음과 같습니다

mkdocs.yml 파일에 다음 Bare-Minimum 구성을 추가하십시오

MKDOCS는“mkdocs”,“Docs 읽기”및“부트 스트랩”과 같은 여러 가지 테마를 배송합니다. 기본 테마를 사용하겠다고 가정 해 봅시다. 이 경우 위의 코드에서 readthedocs를 MKDocs로 교체합니다. 페이지 구성은 문서 및 내비게이션 메뉴를 위해 빌드해야 할 페이지 세트를 결정하는 데 사용됩니다. 페이지에 추가 된 마크 다운 파일은 Docs 폴더와 관련이 있어야합니다. 예를 들어 Docs 디렉토리 내부에서 Config라는 새 폴더를 생성하고 Setup.md 파일을 추가 한 경우 MKDOCS.YML 파일 구성의 페이지에 추가하는 방법은 다음과 같습니다.

이것은 문서 메뉴에 자동으로 나타나는 새로운 페이지를 만듭니다. 첫째, "시작하기"라는 제목이있는 시작 .md 페이지가 있습니다.

우리는 또한“configuration”이라는 문서 메뉴에 새 섹션을 추가했으며, 여기서 새 설정 및 디버그 페이지에 대한 링크가 있습니다. MKDOC에는 내장 웹 서버가 포함되어 있으므로 작업 할 때 문서를 로컬로 미리 볼 수 있습니다. 웹 서버를 시작하려면 mkdocs.yml config 파일이있는 디렉토리에 있는지 확인한 다음 mkdocs serve 명령을 실행하십시오. 브라우저에서 http://127.0.0.1:8000을 방문하여 문서를 보려면

생성 한 내용에 만족하면 MKDocs 빌드를 실행하여 사이트 디렉토리에 저장 될 문서의 정적 파일을 생성합니다. 정적 파일을 복사하여 문서를 생중계하기로 선택한 웹 서버에서 호스팅 할 수 있습니다.

다음 섹션에서는 문서와 github 페이지를 읽기 위해 MKDOC를 배포하는 방법을 배웁니다. 배포 mkdocs 먼저 파일을 저장하기 위해 github (또는 bitbucket) 저장소를 만듭니다. https://github.com/collizo4sky/sitepoint_mkdocs는 내 자신의 mkdocs repo :

여기서 github에 배포 할 다음 명령을 실행합니다. 이제 문서 파일을 배포하여 무료 문서 서비스 인 문서를 읽으십시오. 문서를 읽으십시오 먼저 계정이없는 경우 계정을 만듭니다. 프로젝트 가져 오기 버튼을 클릭하거나 프로젝트 추가 메뉴 항목을 클릭하십시오. GitHub 또는 Bitbucket 계정을 연결하여 전체 프로젝트를 가져 오려는 문서를 읽을 수 있습니다. 대신 수동 프로젝트 가져 오기 버튼을 클릭하여 수동 가져 오기로 이동합니다.

아래 이미지에 표시된대로 양식을 채 웁니다

GitHub에서 문서를 성공적으로 가져 오면 프로젝트 페이지로 리디렉션됩니다.

http://sitepoint-doc.readthedocs.org/en/latest/ 하위 도메인의 문서를 원한다면 DNS의 CNAME 레코드를 프로젝트의 하위 도메인에 가리 킵니다. 예를 들어 docs.sitepoint.com에서 문서를 사용할 수 있도록 sitepoint-doc.readthedocs.org를 가리키는 cname 레코드를 만듭니다.

github 페이지

이제 또 다른 무료 호스팅 서비스 인 GitHub 페이지에서 문서를 호스팅하는 방법을 살펴 보겠습니다. 우리의 경우 마스터 브랜치 인 git 저장소의 작업 지점에 있는지 확인하십시오. 명령 mkdocs gh-deploy -clean 를 실행하십시오 무대 뒤에서이 명령은 문서를 만들어 GH-PAGE 지점에 커밋 한 다음 지점을 GitHub로 밀어냅니다.

여기 Github 페이지에서 itepoint 문서의 데모가 있습니다. 기타 제공자 정적 파일을 제공 할 수있는 모든 호스팅 제공 업체는 MKDocs가 생성 한 문서를 제공하는 데 사용될 수 있습니다. 다음 지침은 일반적인 지원을 제공해야합니다 MKDocs 빌드 명령을 사용하여 사이트를 빌드 할 때 모든 파일은 mkdocs.yaml config 파일의 site_dir configuration 옵션 ( "사이트"로 기본값으로 "사이트")에 지정된 디렉토리에 기록됩니다.

해당 디렉토리의 내용을 호스팅 제공 업체 서버의 루트 디렉토리에 간단히 복사하면 완료됩니다. 또는 문서가 귀하의 사이트의 하위 섹션 일 경우 파일을 지정된 하위 폴더로 옮기십시오.

.

요약 이 튜토리얼에서는 파이썬 정적 웹 사이트 생성기 인 MKDocs와 함께 문서를 작성하는 방법과 GitHub 페이지에서 무료로 문서를 배포하고 호스팅하는 방법을 배웠습니다.

전에 MKDOC를 사용해 보셨습니까? 그렇지 않다면 사용하는 것을 고려 하시겠습니까? 현재 사용자에게 서빙 문서를 어떻게 처리합니까? 피드백을 듣거나 질문에 답변하고 싶습니다.

MKDocs를 사용한 제품 문서 구축에 대한 자주 묻는 질문 (FAQ) mkdocs를 사용하기위한 전제 조건은 무엇입니까?

mkdocs를 사용하려면 시스템에 Python을 설치해야합니다. MKDocs는 Python 버전 2.7, 3.5, 3.6, 3.7, 3.8 및 Pypy를 지원합니다. 명령 프롬프트에서 Python - Version을 입력하여 Python 버전을 확인할 수 있습니다. Python이 성공적으로 설치되면 버전 번호가 표시됩니다. 그렇지 않은 경우 먼저 Python을 설치해야합니다. Python이 설치된 후 Python 패키지 설치 프로그램 인 PIP를 사용하여 MKDOC를 설치할 수 있습니다. MKDocs를 설치하려면 명령 프롬프트에 MKDOC를 설치하는 PIP를 입력하십시오.

MKDocs 사이트의 모양을 사용자 정의하는 방법은 무엇입니까? MKDocs는 테마를 사용하여 사이트의 모양을 제어합니다. 기본 테마는 "MKDocs"라고하지만 다른 많은 테마가 있습니다. mkdocs.yml 구성 파일을 편집하여 테마를 변경할 수 있습니다. 테마 섹션에서 MKDocs를 원하는 테마의 이름으로 바꾸십시오. 일부 테마는 또한 사용자 정의 CSS 또는 JavaScript 파일을 추가하여 추가 사용자 정의를 허용합니다.

MKDocs 사이트에 새 페이지를 추가하는 방법

새 페이지를 추가하려면 먼저 새 마크 다운을 만듭니다. 문서 디렉토리의 파일. 파일 이름은 페이지의 URL로 사용됩니다. 그런 다음 mkdocs.yml 구성 파일의 페이지 섹션에 새 항목을 추가하십시오. 형식은 - [‘페이지 제목’,‘filename.md’]입니다. 페이지 제목은 탐색 메뉴에서 링크 텍스트로 사용됩니다.

MKDocs 사이트를 배포하려면 어떻게해야합니까?

MKDoc에는 GitHub 페이지에 대한 내장 배포 명령이 포함되어 있습니다. 명령 프롬프트에서 MKDOCS GH-DEPLOY를 실행하면 MKDOC가 사이트를 구축하여 GitHub 저장소의 GH-PAGE 지점으로 푸시합니다. 다른 공급자에게 배포하려면 MKDocs 빌드를 사용하여 사이트를 구축 한 다음 사이트 파일을 수동으로 업로드해야합니다. Docs를 읽고 MKDocs를 사용할 수 있습니까?

예, MKDocs는 인기있는 문서 호스팅 플랫폼 인 Docs를 읽는 것과 완전히 호환됩니다. 문서를 읽은 MKDoc을 사용하려면 리포지토리의 루트에 .readthedocs.yml 구성 파일을 생성하고 mkdocs를 문서화 유형으로 지정해야합니다.

mkdocs를 어떻게 업데이트합니까?

PIP 설치 - 명령 프롬프트에서 MKDOC를 업그레이드하여 MKDOC를 업데이트 할 수 있습니다. 이것은 최신 버전의 MKDocs를 다운로드하여 설치합니다.

개인 문서에 MKDocs를 사용할 수 있습니까?

예, 개인 문서에 MKDOC를 사용할 수 있습니다. 그러나 내장 Github 페이지 배포를 사용하는 경우 문서에 공개적으로 액세스 할 수 있습니다. 문서를 비공개로 유지 해야하는 경우 비밀번호 보호 또는 액세스 제어를 지원하는 다른 호스팅 제공 업체를 사용할 수 있습니다.

MKDocs 사이트에 검색 기능을 추가하려면 어떻게합니까? 테마에는 내장 검색 기능이 포함됩니다. 테마가 검색이 포함되어 있지 않거나 다른 검색 공급자를 사용하려면 mkdocs.yml 구성 파일에 검색 플러그인을 추가 할 수 있습니다. 문서화?

MKDocs는 PDF가 아닌 HTML 웹 사이트를 생성하도록 설계되었습니다. 그러나 MKDocs 사이트를 PDF로 변환 할 수있는 타사 도구와 서비스가 있습니다.

MKDocs 사이트에 내비게이션 메뉴를 추가하는 방법은 무엇입니까?

탐색 메뉴가 자동으로 생성됩니다. mkdocs.yml 구성 파일의 페이지 섹션에서 페이지 섹션의 각 항목은 탐색 메뉴의 링크가됩니다. 링크의 순서는 페이지 섹션의 항목 순서와 일치합니다.

위 내용은 MKDocs와 함께 제품 문서 구축의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!