awesometic/mkdocs-material-brief-guide.md

## mkdocs-material-brief-guide.md

      
    Raw
  

              mkdocs-material-brief-guide.md
            
          
    Writing References

이 문서에선 문서 작성 시 규칙과 Material for MkDocs의 자주 쓰이는 기능들에 대해서만 설명합니다.
기본적인 마크다운 문서 작성 방법은 이 링크에 설명이 잘 되어 있기 때문에 생략합니다.
더 많은 Material for MkDocs 사용법은 아래 링크에서 확인해주세요.

Github
기본 기능
확장 기능

해당 문서를 참고할 땐 오른쪽의 Table of contents를 이용해주시면 더 편합니다.
문서 발행 방법

DocuWiki와 다르게 문서 파일을 직접 서버에 업로드해야 합니다.
문서의 위치는 docs이며, 주제 별로 디렉토리를 만들 수 있습니다.
문서 작성

만약 ODROID-N2의 OS 관련한 문서를 작성한다면 해당 문서를 docs/odroid-n2/os.md 로 저장합니다.
설정 파일 수정

이 위키는 정적 웹사이트이기 때문에 새로운 문서 발행 시 build를 통해 html 문서를 생성해줘야 합니다.
build 시 각 문서가 어디에 있다는 걸 선언하기 위해 mkdocs.yml 파일을 수정해야 합니다.
해당 파일 맨 마지막 부분에 아래와 같은 내용이 있습니다.
# Page tree
nav:
  - Index: index.md
  - Another:
    - another-index: another/index.md
    - another-first: another/first.md
    - another-second: another/second.md
  - Getting started: getting-started.md
  - Release notes: release-notes.md
  - License: license.md

방금 만든 새로운 문서를 추가한다면 다음과 같이 바뀌어야 합니다.
# Page tree
nav:
  - Index: index.md
  - Another:
    - another-index: another/index.md
    - another-first: another/first.md
    - another-second: another/second.md
  - Getting started: getting-started.md
  - Release notes: release-notes.md
  - License: license.md
  - ODROID-N2 OS: odroid-n2/os.md

빌드

문서를 작성하고, 설정 파일까지 수정했다면 마지막으로 build만 하면 됩니다.
build 방법은 서버에 접속한 후 다음 명령어를 입력하면 됩니다. Docker로 구축한 경우가 아니라면 적절한 경로에서 mkdocs build만 입력하시면 됩니다.
docker exec -it mkdocsmat-mkdocsmat mkdocs build

문서 수정

이미 빌드된 문서는 파일 수정만으로 실시간 반영됩니다. 새로운 문서 발행이 아닌 오타 수정이나 내용 수정/추가는 단순히 해당 문서를 에디터로 열어 수정하시면 됩니다.
문서 작성 규칙


모든 문서 파일 확장자는 .md 입니다.


파일 이름은 모두 소문자로, 띄어쓰기는 -로 대신합니다.

문서 제목

Getting Started.md


Good

getting-started.md


Bad

getting started.md
gettngStarted.md
getting_started.md


CLI 환경을 설명할 때 root 사용자가 아니라고 가정하여 sudo를 항상 적도록 합니다. 그리고 쉘 프롬프트는 생략하여 명령어만 적습니다. 복사/붙여넣기가 쉽도록 하기 위함입니다. 예를 들면 다음과 같습니다.

Good


sudo apt install git
git clone https://github.com/hardkernel/wiringPi
cd wiringPi
sudo ./build
- Bad

root@odroid:~# apt install git
root@odroid:~# git clone https://github.com/hardkernel/wiringPi
root@odroid:~# cd wiringPi
root@odroid:~# ./build
# apt install git
# git clone https://github.com/hardkernel/wiringPi
# cd wiringPi
# ./build
$ sudo apt install git
$ git clone https://github.com/hardkernel/wiringPi
$ cd wiringPi
$ sudo ./build
odroid@odroid:~$ sudo apt install git
odroid@odroid:~$ git clone https://github.com/hardkernel/wiringPi
odroid@odroid:~$ cd wiringPi
odroid@odroid:~$ sudo ./build

문서를 작성할 땐 아래 템플릿을 따라 작성합니다. 복사해서 사용하세요.

템플릿

# 제목

내용

## 부제 1

내용

## 부제 2

내용

### 부-부제 1

내용

### 부-부제 2

내용

## 부제 3

내용

## 참고

- [Github](https://github.com)

- https://github.com
이미지

모든 이미지는 docs/assets/images 디렉토리에 넣어야 합니다.
글에 이미지를 삽입하기 위해선 다음과 같이 작성합니다.
docs/assets/images의 경로는 상대 경로로 지정합니다. 만약 해당 문서가 docs/another 처럼 docs 밑에 다른 디렉토리에 있다면 다음과 같이 입력합니다.
![](../assets/images/image.jpg)
이미지의 크기는 조절할 수 없습니다.
노트

작성법

아래와 같이 !!! note 아래 줄에 내용을 입력하세요.
!!! note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
제목을 넣을 수도 있습니다.
!!! note "Phasellus posuere in sem ut cursus"
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
종류


!!! note


!!! abstract


!!! info


!!! tip


!!! success


!!! question


!!! warning


!!! failure


!!! danger


!!! bug


!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! abstract
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! info
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! tip
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! success
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! question
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! failure
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! danger
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
!!! bug
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
코드 작성

코드 블럭

```c
#include <stdio.h>

int main() {
    printf("Hello world! \n");

    return 0;
}
```
#include <stdio.h>

int main() {
    printf("Hello world! \n");

    return 0;
}
코드 블럭에서 특정 라인을 강조할 수 있습니다.
```c hl_lines="1 4 5 6"
#include <stdio.h>

int main() {
    printf("Hello world! \n");

    return 0;
}
```
#include <stdio.h>

int main() {
    printf("Hello world! \n");

    return 0;
}
인라인 코드 블럭

커널 업데이트가 완료됐는지 확인하기 위해 `uname -a`를 입력해주세요.

커널 업데이트가 완료됐는지 확인하기 위해 uname -a를 입력해주세요.

인라인 코드 블럭에서도 문법 강조가 가능합니다.
자바 스크립트에선 `#!js var test = 0;` 와 같이 변수를 선언합니다.

자바 스크립트에선 #!js var test = 0; 와 같이 변수를 선언합니다.

코드 블럭 탭

코드 블럭은 탭으로 나눌 수 있습니다. 아쉽지만 평문이 아닌 일반 Markdown 문서는 불가능합니다.
``` bash tab="Bash"
#!/bin/bash

echo "Hello world!"
```

``` c tab="C"
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
}
```

``` c++ tab="C++"
#include <iostream>

int main() {
  std::cout << "Hello world!" << std::endl;
  return 0;
}
```

``` c# tab="C#"
using System;

class Program {
  static void Main(string[] args) {
    Console.WriteLine("Hello world!");
  }
}
```

``` tab="Plain text"
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
```
#!/bin/bash

echo "Hello world!"
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
}
#include <iostream>

int main() {
  std::cout << "Hello world!" << std::endl;
  return 0;
}
using System;

class Program {
  static void Main(string[] args) {
    Console.WriteLine("Hello world!");
  }
}
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

강조

동해물과 ==백두산== 이 마르고 닳도록 하느님이 보우하사 ==우리나라 만세==

동해물과 ==백두산== 이 마르고 닳도록 하느님이 보우하사 ==우리나라 만세==

체크 리스트

* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
* [x] Nulla lobortis egestas semper
* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
* [ ] Vestibulum convallis sit amet nisi a tincidunt
    * [x] In hac habitasse platea dictumst
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
    * [ ] Praesent sed risus massa
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi

 Lorem ipsum dolor sit amet, consectetur adipiscing elit
 Nulla lobortis egestas semper
 Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
 Vestibulum convallis sit amet nisi a tincidunt

 In hac habitasse platea dictumst
 In scelerisque nibh non dolor mollis congue sed et metus
 Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
 Praesent sed risus massa


 Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
 Nulla vel eros venenatis, imperdiet enim id, faucibus nisi

데이터 테이블

| Sollicitudo / Pellentesi | consectetur | adipiscing | elit    | arcu | sed |
| ------------------------ | ----------- | ---------- | ------- | ---- | --- |
| Vivamus a pharetra       | yes         | yes        | yes     | yes  | yes |
| Ornare viverra ex        | yes         | yes        | yes     | yes  | yes |
| Mauris a ullamcorper     | yes         | yes        | partial | yes  | yes |
| Nullam urna elit         | yes         | yes        | yes     | yes  | yes |
| Malesuada eget finibus   | yes         | yes        | yes     | yes  | yes |
| Ullamcorper              | yes         | yes        | yes     | yes  | yes |
| Vestibulum sodales       | yes         | -          | yes     | -    | yes |
| Pulvinar nisl            | yes         | yes        | yes     | -    | -   |
| Pharetra aliquet est     | yes         | yes        | yes     | yes  | yes |
| Sed suscipit             | yes         | yes        | yes     | yes  | yes |
| Orci non pretium         | yes         | partial    | -       | -    | -   |

| Left       | Center   | Right   |
| :--------- | :------: | ------: |
| Lorem      | *dolor*  | `amet`  |
| [ipsum](#) | **sit**  |         |


Sollicitudo / Pellentesi
consectetur
adipiscing
elit
arcu
sed


Vivamus a pharetra
yes
yes
yes
yes
yes


Ornare viverra ex
yes
yes
yes
yes
yes


Mauris a ullamcorper
yes
yes
partial
yes
yes


Nullam urna elit
yes
yes
yes
yes
yes


Malesuada eget finibus
yes
yes
yes
yes
yes


Ullamcorper
yes
yes
yes
yes
yes


Vestibulum sodales
yes
-
yes
-
yes


Pulvinar nisl
yes
yes
yes
-
-


Pharetra aliquet est
yes
yes
yes
yes
yes


Sed suscipit
yes
yes
yes
yes
yes


Orci non pretium
yes
partial
-
-
-


Left
Center
Right


Lorem
dolor
amet


ipsum
sit


작성자 정보

Yang Deokgyu (awesometic)
Sollicitudo / Pellentesi	consectetur	adipiscing	elit	arcu	sed
Vivamus a pharetra	yes	yes	yes	yes	yes
Ornare viverra ex	yes	yes	yes	yes	yes
Mauris a ullamcorper	yes	yes	partial	yes	yes
Nullam urna elit	yes	yes	yes	yes	yes
Malesuada eget finibus	yes	yes	yes	yes	yes
Ullamcorper	yes	yes	yes	yes	yes
Vestibulum sodales	yes	-	yes	-	yes
Pulvinar nisl	yes	yes	yes	-	-
Pharetra aliquet est	yes	yes	yes	yes	yes
Sed suscipit	yes	yes	yes	yes	yes
Orci non pretium	yes	partial	-	-	-