FreeBSD mkdocs 설치

FreeBSD mkdocs 설치

mkdocs 소개 

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

참고페이지 : https://demun.github.io/mkdocs-tuts/#mkdocs
   : https://www.mkdocs.org/#installation
official site : https://www.mkdocs.org/

사용법참고: https://demun.github.io/mkdocs-tuts/how/

 

mkdocs 설치

root@bsd11:~ # whereis py-mkdocs
py-mkdocs: /usr/ports/textproc/py-mkdocs
root@bsd11:~ #
root@bsd11:~ # cd /usr/ports/textproc/py-mkdocs && make install clean
Installing py27-mkdocs-1.0...
If you are using the Python v3.x version and a non-Unicode locale you'll get a r untime error when mkdocs is executed..
In that case please set the locale to a Unicode locale first, e.g. en_US.UTF-8 o r similar, before starting mkdocs.
~중략
root@bsd11:/usr/ports/textproc/py-mkdocs # rehash

 

mkdocs 사용

default 사용시 127.0.0.18000 로 open 됩니다.

root@bsd11:~ # mkdocs new mkdocs-tuts
INFO - Creating project directory: mkdocs-tuts
INFO - Writing config file: mkdocs-tuts/mkdocs.yml
INFO - Writing initial docs: mkdocs-tuts/docs/index.md
root@bsd11:~ # cd mkdocs-tuts

mkdocs serve 실행시 locale:8000 로 실행 됩니다. 
root@bsd11:~/mkdocs-tuts # mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 180903 22:39:37 server:292] Serving on http://127.0.0.1:8000
[I 180903 22:39:37 handlers:59] Start watching changes
[I 180903 22:39:37 handlers:61] Start detecting changes

 

–dev-addr 옵션 사용시 IP:port 를 지정할수 있습니다.

root@bsd11:~/mkdocs-tuts # mkdocs serve --dev-addr 192.168.0.100:80
INFO - Building documentation...
INFO - Cleaning site directory
[I 180903 22:44:20 server:292] Serving on http://192.168.0.100:80
[I 180903 22:44:20 handlers:59] Start watching changes
[I 180903 22:44:20 handlers:61] Start detecting changes
[I 180903 22:44:26 handlers:132] Browser Connected: http://192.168.0.100/
[I 180903 22:48:21 handlers:132] Browser Connected: http://192.168.0.100/#welcome-to-mkdocs
[I 180903 22:48:23 handlers:132] Browser Connected: http://192.168.0.100/


Port 확인
root@bsd11:~ # sockstat -4
USER COMMAND PID FD PROTO LOCAL ADDRESS FOREIGN ADDRESS
root python2.7 6008 3 tcp4 175.211.33.9:80 *:*
root python2.7 6008 7 tcp4 175.211.33.9:80 192.168.0.10:8713
root python2.7 6008 8 tcp4 175.211.33.9:80 192.168.0.10:8718
root python2.7 6008 9 tcp4 175.211.33.9:80 192.168.0.10:8714
root python2.7 6008 10 tcp4 175.211.33.9:80 192.168.0.10:8715
root python2.7 6008 13 tcp4 175.211.33.9:80 192.168.0.10:8716
root python2.7 6008 15 tcp4 175.211.33.9:80 192.168.0.10:8717
test sshd 5978 3 tcp4 175.211.33.9:22 192.168.0.10:8685
root sshd 5975 3 tcp4 175.211.33.9:22 192.168.0.10:8685
test sshd 755 3 tcp4 175.211.33.9:22 192.168.0.10:8627
root sshd 752 3 tcp4 175.211.33.9:22 192.168.0.10:8627
root sendmail 682 3 tcp4 127.0.0.1:25 *:*
root sshd 679 4 tcp4 *:22 *:*

 

website 접속

Nginx 와 MKdocs 사용예

FreeBSD Nginx 설치는 아래 내용을 참고 하시면 됩니다.

[web-server] Nginx 설치

mkdocs serve 를 통하여 사용하지 않고 nginx or apache 로 구성된 웹서버에서 사용하시면 됩니다.

ex) /var/www/test.com 으로 구성된 nginx home 디렉토리에서 mkdocs-tuts 프로젝트를 만들고

build 까지 한후 web에서 접속한 예제 입니다.

root@bsd11:/var/www/test.com # mkdocs new mkdocs-tuts
INFO    -  Creating project directory: mkdocs-tuts
INFO    -  Writing config file: mkdocs-tuts/mkdocs.yml
INFO    -  Writing initial docs: mkdocs-tuts/docs/index.md
root@bsd11:/var/www/test.com #


root@bsd11:/var/www/test.com # cd mkdocs-tuts/
root@bsd11:/var/www/test.com/mkdocs-tuts # ll
total 1
drwxr-xr-x  2 root  www   3  9  5 01:02 docs/
-rw-r--r--  1 root  www  19  9  5 01:02 mkdocs.yml
root@bsd11:/var/www/test.com/mkdocs-tuts #


root@bsd11:/var/www/test.com/mkdocs-tuts # mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /var/www/test.com/mkdocs-tuts/site
root@bsd11:/var/www/test.com/mkdocs-tuts #

 

접속확인

 

Theme 변경

root@bsd11:/var/www/test.com/mkdocs-tuts # vi mkdocs.yml
site_name: My Docs
theme: readthedocs

root@bsd11:/var/www/test.com/mkdocs-tuts # mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: /var/www/test.com/mkdocs-tuts/site
root@bsd11:/var/www/test.com/mkdocs-tuts #

 

 

dropdown 적용

참고페이지: https://github.com/cjsheets/mkdocs-rtd-dropdown

설치 

test@docker-test:~$ pip install mkdocs-rtd-dropdown

 

http://readthedocs.sheets.ch/#installation

root@bsd11:/var/www/test.com/mkdocs-tuts # cat mkdocs.yml
site_name: Opensource manual
#theme: readthedocs
theme: rtd-dropdown
nav:
  - INFO: index.md
  - Reference:
      Linux: linux/linux.md
      Cloud: cloud/cloud.md
      Languge: lang/lang.md
      FreeBSD: freebsd/freebsd.md

root@bsd11:/var/www/test.com/mkdocs-tuts # tree
.
├── docs
│   ├── cloud
│   │   └── cloud.md
│   ├── freebsd
│   │   └── freebsd.md
│   ├── index.md
│   ├── lang
│   │   └── lang.md
│   └── linux
│       └── linux.md
├── mkdocs.yml
└── site
    ├── 404.html
    ├── centos
    │   └── centos
    │       └── index.html
    ├── cloud
    │   └── cloud
    │       └── index.html
    ├── css
    │   ├── theme_extra.css
    │   └── theme.css
    ├── fonts
    │   ├── fontawesome-webfont.eot
    │   ├── fontawesome-webfont.svg
    │   ├── fontawesome-webfont.ttf
    │   └── fontawesome-webfont.woff
    ├── freebsd
    │   └── freebsd
    │       └── index.html
    ├── how
    │   └── index.html
    ├── img
    │   └── favicon.ico
    ├── index.html
    ├── js
    │   ├── jquery-2.1.1.min.js
    │   ├── modernizr-2.8.3.min.js
    │   └── theme.js
    ├── lang
    │   └── lang
    │       └── index.html
    ├── linux
    │   └── linux
    │       └── index.html
    ├── search
    │   ├── lunr.js
    │   ├── main.js
    │   ├── search_index.json
    │   └── worker.js
    ├── search.html
    ├── sitemap.xml
    ├── sitemap.xml.gz
    └── ubuntu
        └── ubuntu
            └── index.html

24 directories, 32 files
root@bsd11:/var/www/test.com/mkdocs-tuts #
root@bsd11:/var/www/test.com/mkdocs-tuts # cat docs/linux/linux.md
## CentOS

## Ubuntu

### System Command

### Package install
root@bsd11:/var/www/test.com/mkdocs-tuts #

 

 

 

 

 

댓글 남기기