Mkdocs,이 오픈 소스 소프트웨어 덕분에 문서 작성

다음 기사에서 우리는 Mkdocs를 살펴볼 것입니다. 소프트웨어를 개발하고 문서 작성을위한 플랫폼 귀하의 프로젝트 중 하나. 또는 직원을위한 내부 문서를 작성해야하는 회사에서 일하는 경우. 메모를 저장하려는 고급 사용자 인 경우에도 마찬가지입니다. MkDocs는 시도해야 할 도구입니다.

이 소프트웨어는 문서화 플랫폼을 만들기위한 정적 사이트 생성기입니다. 매우 간단하고보기 좋으며 설정 및 배포가 쉽습니다. 이 파이썬으로 작성 그리고 간단히 Markdown 형식으로 파일을 생성해야합니다.. 그런 다음 단일 YAML 구성 파일을 사용하여 자신에게 맞는 정적 웹 사이트를 생성 할 수 있습니다.

다음으로 MkDocs를 사용하여 완전한 문서 웹 사이트를 얻는 것이 얼마나 쉬운 지 살펴 보겠습니다. 다른 많은 것들이 있습니다 사이트 생성기 비슷한 정적이지만 이것은 가장 간단한 구성 및 구현이 있습니다..

일반 사용자도이 소프트웨어를 사용하여 메모 할 로컬 플랫폼을 만듭니다. 자신이나 그와 유사한 것을 위해.

MkDocs 설치

로컬로 설치

MkDocs 설치가 매우 쉽다는 것을 알아 봅시다. 우리는 할 수 있습니다 pip를 사용하여 설치. 터미널을 열고 (Ctrl + Alt + T) 다음과 같이 작성하면됩니다.

pip install mkdocs

설치 후 작업 디렉토리에서 다음 명령을 실행하여 사이트 초기화:

mkdocs new mkdocspro

그리고 서빙 시작 운영:

cd mkdocspro

mkdocs serve

그런 다음 localhost로 이동 : 8000 (또는 포트 8000이있는 IP 주소 / 호스트 이름)을 클릭하여 MkDocs의 작동 방식을 확인하세요.

nginx 서버에 설치

이것은 정적 사이트 생성기이므로 PHP 또는 Python과 같은 백엔드 엔진이 필요하지 않습니다.. 2 분 안에 웹 서버 (nginx, apacheXNUMX)에서 MkDocs 프로젝트를 구현할 수 있습니다. 예를 들어, 다음은 nginx 가상 호스트 구성:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

대체 example.com 서버에있는 도메인으로. 또한 변경해야합니다 / var / www / mkdocspro / 사이트 서버에있는 사이트의 하위 폴더 경로로. 그런 다음 우리는 nginx 다시 시작 다음 명령으로 :

sudo service nginx restart

이제 example.com으로 이동하여 작동하는지 확인할 수 있습니다.

Mkdocs에 다른 테마 설치

기본 Mkdocs 테마는 특별히 좋지 않습니다. 그러나 XNUMX 분 안에 다른 것을 설치할 수 있습니다. 다른 테마의 설치 예는 다음과 같습니다. 우리는 재료 테마 설치:

pip install mkdocs-material

설치 후 테마를 활성화하려면 mkdocs.yml 파일을 편집하고 다음과 유사하게 만드십시오.. 몇 가지 옵션을 추가 할 수 있습니다.

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

옵션은 매우 명확합니다. 그러나 여기에 몇 가지 설명이 있습니다.

• repo_url:입니다 Git 저장소 URL. Git을 MkDocs 프로젝트에 직접 통합하려는 경우이 옵션을 사용하여 사람들이 페이지를 편집하거나 프로젝트를 분기하도록 할 수 있습니다.
• 편집_우리: 이것이 GitHub에서 페이지 편집을위한 접미사. GitLab 또는 GitBucket을 사용하는 경우 변경할 수 있습니다.
• google_analytics: MkDocs에 대한 제어판이 없습니다. 따라서 알고 웹 사이트를 방문하는 사람은 Google Analytics를 사용해야합니다.. 이 옵션을 사용하면 추적 번호를 삽입하여 계정을 웹 사이트와 연결할 수 있습니다.
• 디스 큐스: 네가 원한다면 Disqus 주석 시스템 활성화 웹 사이트에서 여기에 닉네임을 입력 할 수 있습니다.
• 테마: 사용하려는 테마의 이름. 머티리얼 테마에서했던 것처럼 이전에 설치해야합니다. 이것이 우리가 예제에서 사용할 이름이 될 것입니다.

새로운 테마의 변경 사항보기

파일을 저장 한 후 mkdocsproject 폴더 내에서 mkdocs 빌드 실행. 웹 사이트는 머티리얼 테마의 기본 모양과 느낌을 채택합니다.

중요 : 수정 후 항상 mkdocs 빌드를 실행하십시오. 파일에서 수행하는 작업. 그렇지 않으면 변경 사항이 표시되지 않습니다.

많은 사람들이있다 다른 테마 및 옵션 이 소프트웨어를 구성합니다. 당신은 그들을 상담 할 수 있습니다 공식 문서 MkDocs에 의해. 다음은 목록입니다. 가능한 옵션 우리가 사용할 수 있습니다.