mkdocs-material
網站
安裝
pip install mkdocs-material
Admonitions 醒目提醒
Usage
| 類型 | Code | 注意 |
|---|---|---|
| Note | ??? note | 內容起始為 |
| Abstract | ??? abstract | 下一行開始， |
| Info | ??? info | 並且空4格 |
| Tip | ??? tip | |
| Success | ??? success | |
| Question | ??? question | |
| Warning | ??? warning | |
| Failure | ??? failure | |
| Danger | ??? danger | |
| Bug | ??? bug | |
| Example | ??? exanple | |
| Quote | ??? quote |
自動展開內容"
在???後加+
inline Block
Lorem ipsum
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 inline end "Lorem ipsum"
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.
Lorem ipsum
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 inline "Lorem ipsum"
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.
Button
Configuration
markdown_extensions:
- attr_list
Usage
[Subscribe to our newsletter](#){ .md-button }
Primary Buttons
[Subscribe to our newsletter](#){ .md-button .md-button--primary }
Button with icon
[Send :fontawesome-solid-paper-plane:](#){ .md-button }
Code Block
Configuration
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
theme:
features:
- content.code.copy
Usage
```python
code block
```
Add Title
```python title="My Title"
Content
```
My Title
Content
Adding line numbers
```python linenums="1"
Line1 1
Line1 2
Line1 3
```
1 2 3 | |
Highlighting specific lines
``` py hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
Content Tabs
configuration
markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
Usage
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```
=== "C++"
``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
Tables
Configurations
markdown_extensions:
- tables
Usage
| AA | BB | # 標題
|----|----| # 格式
|aa |bb | # 內容
|aaa |bbb |
| AA | BB |
|---|---|
| aa | bb |
| aaa | bbb |
對齊方式 在格式列
| 排列 | 格式 |
|---|---|
| 靠左 | |:---| |
| 置中 | |:---:| |
| 靠右 | |---:| |
Footnote
Configuration
markdown_extensions:
- footnotes
Usage
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
在文件任何地方放下註解，到本頁面最底下看註腳，或是直接按數字
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
[^2]:
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.
Lorem ipsum1 dolor sit amet, consectetur adipiscing elit.2
Formating
Configuration
markdown_extensions:
- pymdownx.critic
- pymdownx.caret
- pymdownx.keys
- pymdownx.mark
- pymdownx.tilde
Usage
Highlight
紅底刪除線 : {- -刪除線- -}
綠底加底線 : {++綠底加底線++}
前面刪除線 後面綠底新增文字 : {~~前面刪除線~>後面綠底新增文字~~}
藍底凸顯文字段落 : {==藍底凸顯文字段落==}
部分字串Highlight
1. ==This was marked==
2. ^^This was inserted^^
3. ~~This was deleted~~
Caret上標 & Tilde下標
- H~2~O
- A^T^A
- ATA
鍵盤健
++ctrl+alt+del++
Grid
Configuration
markdown_extensions:
- attr_list
- md_in_html
Usage
<div class="grid cards" markdown>
- :fontawesome-brands-html5: __HTML__ for content and structure
- :fontawesome-brands-js: __JavaScript__ for interactivity
- :fontawesome-brands-css3: __CSS__ for text running out of boxes
- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
</div>
- HTML for content and structure
- JavaScript for interactivity
- CSS for text running out of boxes
- Internet Explorer ... huh?
List
Configuration
markdown_extensions:
- def_list
- pymdownx.tasklist:
custom_checkbox: true
Usage
- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
- Lorem ipsum dolor sit amet, consectetur adipiscing elit
- Vestibulum convallis sit amet nisi a tincidunt
- In hac habitasse platea dictumst
- In scelerisque nibh non dolor mollis congue sed et metus
- Praesent sed risus massa
- Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
Highligh
使用 pygments
官網：pygments
Options
| Option | Type | Default | Description |
|---|---|---|---|
| css_class | string | 'highlight' | Default class to apply to the wrapper element on code blocks. Other extensions can override this. |
| guess_lang | bool | False | Guess what syntax language should be used if no language is specified. True for always, False for never, 'block' for block code only, and 'inline' for inline code only. |
| pygments_style | string | 'default' | Set the Pygments' style to use. This really only has an effect when used with noclasses. |
| noclasses | bool | False | This will cause the styles to directly be written to the tag's style attribute instead of requiring a stylesheet. |
| use_pygments | bool | True | Controls whether Pygments (if available) is used to style the code, or if the code will just be escaped and prepped for a JavaScript syntax highlighter. |
| linenums | bool | None | Enable line numbers globally for block code. This will be ignored for inline code. If set to False line numbers will be disabled globally and can not be turned on, not even per code block. |
| linenums_special | int | 1 | Globally sets the specified nth lines' gutter with the class "special". This can be overridden in SuperFences per fence if desired. |
| linenums_style | string | 'table' | Controls the output style when linenums are enabled. Supported styles are Pygments default table and inline, but also supported is the pymdown-extensions pymdownx-inline which provides a special inline mode, see Line Number Styles for more info. |
| linenums_class | string | 'linenums' | Controls the name of the line number class when Pygments is not used. |
| extend_pygments_lang | list | [] | A list of extended languages to add. See Extended Pygments Lexer Options for more info. |
| language_prefix | string | 'language-' | Controls the prefix applied to the language class when Pygments is not used. By default, uses the HTML5 prefix of language-. |
| code_attr_on_pre | bool | False | By default, the language class and all attributes added via the attr_list extension are attached to the <code> element. This forces them to be attached to the <pre> element. |
| auto_title | bool | False | When using Pygments, for all code blocks generate a title header with the name of the lexer being used. The lexer name is pulled directly from Pygments and title cased appropriately. |
| auto_title_map | dict | {} | A dictionary used to override certain titles returned by auto_title. Simply specify the title to override as the key and the desired title as the value. |
| line_spans | string | '' '' | Controls the Pygments option of a similar name. If set to a nonempty string, e.g. foo, the formatter will wrap each output line in a tag with an id of foo-<code_block_number>-<line_number>. |
| anchor_linenums | bool | False | Enables the Pygments option of a similar name. If set to True, will wrap line numbers in tags. Used in combination with linenums and line_anchors. If line_anchors is not configured, __codelineno will be assumed as the ID prefix. |
| line_anchors | bool | False | Controls the Pygments option of a similar name. If set to a nonempty string, e.g. foo, the formatter will insert an anchor tag with an id (and name) of foo-<code_block_number>-<line_number>. |
| pygments_lang_class | bool | False | If set to True, the language name used will be included as a class attached to the element with the associated language_prefix. |
在 mkdocs.yml 設定
markdown_extensions:
- pymdownx.highlight:
use_pygments: true # 使用pygment 替程式碼上色
noclasses: true # 要指定style 就要讓 noclasses=true
pygments_style: native #
guess_lang: true
line_spans: __span
- pymdownx.superfences: # 使用 pymdownx.highlight 一定要有
preserve_tabs: true