Gitbook - 블로그 문서화 플랫폼

숲사람·2022년 3월 23일
0

유용한 도구

목록 보기
1/5

gitbook?

documentation 블로그 만드는 플랫폼
예시 사이트: http://soopsaram.com/ml

gitbook 설치


$ npm install gitbook-cli -g  

gitbook 디렉토리 구조 생성


$ gitbook init ./mygitbook  

gitbook 서버 실행


$ gitbook serve  
  
...  
Starting server ...  
Serving book on http://localhost:4000  

그러면 localhost:4000 로 접속 가능.

생성된 디렉터리,파일 구조


  • 기본 디렉터리 구조
.  
├── README.md  
├── SUMMARY.md  
└── _book/		# server 실행하면 자동생성됨. (index.html 등생성)  
  • SUMMARY.md

목차 생성 파일

# Summary  
  
* [Introduction](README.md)  
  

README.md 파일 하나로 목차 생성함.

  • README.md
# 1. Introduction  

SUMARY.md 간단한 예시


# Summary  
  
* [Introduction](README.md)  
  
* [Part I](part1/README.md)  
	* [Writing is nice](part1/writing.md)  
	* [GitBook is nice](part1/gitbook.md)  
* [Part II](part2/README.md)  
	* [We love feedback](part2/feedback_please.md)  
	* [Better tools for authors](part2/better_tools.md)  

tab으로 들여쓰기 하면 목차도 들여쓰기로 생성됨.

  • 이에 해당하는 디렉터리 구조
    대충 아래와 같이 md파일 생성
├── book.json            # 기본 GitBook구성 데이터(선택)  
├── README.md            # 서적 소개(필수)  
├── SUMMARY.md           # 목차 참조(선택)  
├── GLOSSARY.md          # 용어 정리(선택 : 직접파일 성생필요)   
├── chapter-1/  
|   ├── README.md  
|   └── something.md  
└── chapter-2/  
    ├── README.md  
    └── something.md  

book.json 에는 사용할 플러그인 등을 설정할 수 있다.

github에 배포하기


repo를 생성하고 gh-pages 브랜치를 생성하고 _books/ 디렉터리를 반영하면 jihuun.github.io/repo-name 으로 gitbook이 반영됨! (신기)

$ git clone git@github.com:username/repo-name.git  
$ cd repo-name  
$ git checkout -b gh-pages  
  
# ../mygitbook/ 에서 파일생성 및 gitbook serve 했다고 가정   
$ cp -R ../mygitbook/_book/* . #*  
$ git clean -fx node_modules  
$ git clean -fx _book  

그뒤 커밋 생성후

git push origin gh-pages  

google analytics 추가하기


다시 test 디렉터리로 이동
book.json 생성

{  
    "plugins": ["ga"],  
    "pluginsConfig": {  
        "ga": {  
            "token": "???????8-1"  
        }  
    },  
    "variables": {  
        "BASE_URL": "http://soopsaram.com/ml/"  
    }  
}  
 $ gitbook serve  
...  
Error: Couldn't locate plugins "ga", Run 'gitbook install' to install plugins from registry.  
  
  • GA plugin 설치 필요.
$ npm install gitbook-plugin-ga -g  
$ gitbook install  

-g 옵션으로 전역 설치

LaTeX 수식 입력하기 : mathjax 플러그인 설치


참고 새로고침을 해야 수식이 표기되는 문제가 수정되지 않은것같아서 마지막에 최종 해결방법대로 함.

  • 기본 사용법
$ npm i gitbook-plugin-mathjax -g  
$ gitbook install  
  • book.json 에 플러그인 명시
{  
    "plugins": ["mathjax"]  
}  

https://gitbookio.gitbooks.io/documentation/format/math.html

  • 수식 기입방법

인라인 수식이나 일반 수식 모두 $$ 두개를사용해야함.

$$  
y = x^2  
$$  
$$ y = x^2 $$  

플러그인 없이 사용방법

md 파일 최상단에 아래 삽입.

<script type="text/x-mathjax-config">  
        MathJax.Hub.Config({  
        tex2jax: {  
	        inlineMath: [ ['$','$'], ["\\(","\\)"] ],  
	        displayMath: [ ['$$','$$'], ["\\[","\\]"] ],  
	        processEscapes: true  
        },  
        });  
</script>  
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">  
</script>   
  
<script> MathJax.Hub.Queue(["Typeset",MathJax.Hub]); </script>  

이렇게 할때 아래 같은 여러줄은 동작을 안함. $$ .. $$ 이 한줄이 되어야함.

$$  
x^2  
$$  
  • $$ $$ 찾아서 한줄로 옮기기 -> vim으로 추후 작업하기.
    첫번째 $$ 찾는 regex
    마지막 $$ 찾는 regex ? \$\$\+$

최종 해결방법 : script 삽입

참고:

  1. math.md 파일 생성 하고 아래내용 추가

    <script type="text/x-mathjax-config">  
    	MathJax.Hub.Config({  
    	tex2jax: {  
    		inlineMath: [ ['$','$'], ["\\(","\\)"] ],  
    		displayMath: [ ['$$','$$'], ["\\[","\\]"] ],  
    		processEscapes: true  
    	},  
    	});  
    </script>  
    <script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">  
    </script>   
    
    <script> MathJax.Hub.Queue(["Typeset",MathJax.Hub]); </script>  

    MathJax.Hub.Config 는 ...... 로 inline math를 사용하기 위함임.
    마지막 MathJax.Hub.Queue 때문에 페이지 새로고침 없이도 정상동작(이유는 모름)

  2. 모든 문서 md파일 마다 최상단에 아래 기입

    {% include "../math.md" %}  

    대신 $$ ... $$ 한줄에 써야함.

KaTeX 사용하기 (나는 안씀)

https://github.com/GitbookIO/plugin-katex

  • \underset이 parsing 안됨.
    KaTeX버전이 낮아서 생기는 문제인듯
  ParseError: KaTeX parse error: Expected 'EOF', got '\underset' at position 2:  \̲u̲n̲d̲e̲r̲s̲e̲t̲{\theta_0 , \th…  

\underset 뿐만아니라 지원하지 않는 문법(?)이 너무 많아서 못쓰겠음.

gitbook proxy 설정


회사등 proxy환경일경우 설정방법.
아래와 같이 설정하면 ~/.npmrc 파일에 추가됨. 확인은 $ npm config list

 $ npm config set proxy http://168.219.61.252:8080  
 $ npm config set https-proxy https://168.219.61.252:8080  
 $ npm config set strict-ssl false  

Trouble Shooting

참고 블로그

profile
기록 & 정리 아카이브 용도 (보다 완성된 글은 http://soopsaram.com/documentudy)

0개의 댓글