# Siyuan

> 

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-6yi0dv5/20200924101106-19z4kaa.sy -->

# What is a Content Block

## Content block definition

"Content block" refers to a piece of content, and each piece of such content is identified by a globally unique ID. The ID is automatically generated by the program and has the form: `202008250000-a1b2c3d`, consisting of time and 7 random characters.

## Content block types

The most common content block is the familiar paragraph (Paragraph). In traditional Chinese typesetting, paragraphs are usually represented by indentation (two spaces) at the beginning of the paragraph. With the development of the Internet, it has gradually affected the representation of paragraphs. The most commonly used method is to increase the line spacing between paragraphs, or use blank lines to separate paragraphs.

In actual use, it is not enough to rely on paragraph typesetting. It is often necessary to use Heading, List, Table, Blockquote, etc. to enrich our typesetting. These typographic styles are not only visually different, but more importantly, they express the semantics of the content to a certain extent. For example, when we see an unordered list, we can know that each list item is in an indiscriminate level relationship, while when we see an ordered list, the opposite is true.

Therefore, there are many content blocks types, and different types of content blocks are defined by formatting. Content block/Type

## Combined content blocks

A document is a combination of some content blocks, and the content block is the basic unit. This is like Lego bricks, which can be combined using different basic modules. Note: the document itself is also a kind of content block. More precisely, the three content blocks of document block, list block, and block reference block are container blocks, and they can contain any other types of content blocks. Content block/Combine

At this point, we have been able to use content blocks to describe all content, so that we can use uniform usage to link content block . Logically, there is no page concept, which reduces unnecessary burdens in use and allows users to focus on the content block.

## Naming and memo

We can name each content block, add aliases and memo. Naming and aliases are mainly used for anti-link mention search, and memo are used to record some inconvenient information in the content area.

After opening the options for displaying bookmarks, naming, and alias identification in the <kbd>Settings</kbd> - <kbd>Editor</kbd>, the named content block will be displayed with a frame in the editor. If you name and memo the document block, when the mouse is hovering over the doc tree document, the relevant naming and memo of the document will appear.

You can use Embed Content Block to search and summarize the naming and memo, such as listing the content blocks that contain the keyword `short` in the memo:

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-6yi0dv5/20200924101200-gss5vee.sy -->

# Navigate in the Content Block

## Link

There are two types of links in the document content:

- Standard URL hyperlinks, opened with a browser, used for Internet resource access
- The content block link established by `((id))` is used for two-way linking within SiYuan

## Zoom focus

- After selecting focus in the right-click drop-down menu on the block icon, the editor will focus on the content block
- Jump in context through the breadcrumb navigation at the top of the editor

## Graph

The relationship diagram is divided into document level and global. The relationship diagram of the document is expanded based on the current document block and presents all the content blocks (forward links and reverse links) related to the document; the global relationship diagram is all the block and link relationships in all notebooks.

Hold down `Ctrl` and click on the node: jump to the node.

## Backlinks

Backlinks are document-level, listing the blocks in the current document where content blocks are quoted and mentioned.

### Links

- Hovering the mouse over the reference block icon will pop up a preview floating window
- Click the reference block in the backlink list to jump

### Mentions

It is mentioned that the name and aliases of the content block in the current document is used as a keyword to search, and the search result is a content block containing these keywords. You can use the link button to convert the mention into a link: the mention will be replaced with `((id "content block name"))`.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-6yi0dv5/20200924101225-k254i8g.sy -->

# Content Block Type

## Content Block type cheatsheet

Hover the mouse over the content block and the corresponding icon will appear on the left side of the content block. For format usage, please refer to Markdown Complete Demo.

| Icon | Type | Meta Type |
|---|---|---|
|  | Paragraph block | Leaf block |
|  | Heading block | Leaf block |
|  | Math Formula block | Leaf block |
|  | Code block | Leaf block |
|  | Table block | Leaf block |
|  | HTML block | Leaf block |
|  | Unordered List block | Container block |
|  | Ordered List block | Container block |
|  | Task list block | Container block |
|  | List Item block | Container block |
|  | Blockquote block | Container block |
|  | Super block | Container block |
|  | Document block | Container block |

## Details of content block types

Below we introduce the details of these content block types. Content block/Type

### Paragraph block

Here is a sample paragraph.

Press Enter directly after a paragraph to form a new paragraph.

### Heading block

The above is the heading block, which supports level one to six.

### Mathematical formula block

$$
a^2 + b^2 = c^2
$$

### Code block

```anM=
function hello() {}
```

### Table block

| Column 1 | Column 2 |
|---|---|
| Row One Column One | Row One Column Two |
| Row Two Column One | Row Two Column Two |

If you need to use `|` in the form, please use `\` to escape, that is, you need to enter `\|`.

### HTML block

<ruby>
你<rt>nǐ</rt>
　好<rt>　hǎo</rt>
　世<rt>　shì</rt>
　界<rt>　jiè</rt>
</ruby><br>
Hello World

Note: The code in the HTML block will not be safely filtered when using it. Please confirm the code is safe before using it to avoid cross-site scripting (XSS).

### Unordered List Block

- List item one
- List item two

The unordered list block is a type container block.

If you need to wrap a line in a list item, use <kbd>Shift Enter</kbd>.

### Ordered List Block

1. List item one
2. List item two

An ordered list block is a type container block.

### Task list block

- To do one
- To do two

The task list block is a type container block.

### List item block

The basic usage of outline notes can be realized through the list item block. The list item block is a type container block.

### Blockquote Block

> Note that it is not a content block ref, but a block quote (Blockquote).

The block reference block is a type container block.

### Super block

The super block is a type container block. It can be used to combine continuous content blocks in a document, and also to support horizontal typesetting.

### Documentation block

The entire document is a block, and the document block is a type container block.

## Content Block meta type

The content block is logically divided into a leaf block and a container block. The leaf block cannot contain other blocks, and the container block can contain other blocks:

- List block: can only contain list item blocks
- List item block: can contain any other non-document blocks
- Blockquote block: can contain any non-document blocks
- Super block: can contain any non-document blocks
- Document block: can contain any non-document blocks

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-6yi0dv5/20200924101256-f8b1sbi.sy -->

# Ref Content Block

## Overview

Entering `((` will trigger the content block quotation search, continue to enter as the search keyword, use the up and down keys to select in the search results and press Enter to complete the content block quotation.

The complete syntax of the content block quote is: `((id "text"))`, where the `id` is like: `202008250000-a1b2c3d`, consisting of time and 7 random characters, the content block id is when the content block is created It will be automatically generated; the following `text` is the custom anchor text for the content block in the quote. After the content block quote is established, hover the mouse over the anchor text and a preview floating layer will pop up to show the quoted content block. Content block/Reference

## Direction of the ref link

- Forwardlink, that is, which other content blocks are used in the current content block
- Backlink, that is, the current content block is used by those other content blocks

The forward link is included in the content of the current block, which we can see intuitively. Backlinks need to be searched in other documents to know, and it is precisely this information that is more valuable to us. We can use the following two ways to help us better grasp the knowledge points or diverge ideas:

- Graph: browse forward and backward link relationships between content blocks
- Backlinks: Display the backlinks of the current content block as a text list

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-6yi0dv5/20201117112518-dott91x.sy -->

# Embed Content block

## Overview

The embed content block is mainly used to summarize the required content blocks, use `{{` and `}}` to wrap SQL scripts on a single line: `{{ SELECT * FROM blocks WHERE content LIKE'%Keyword%' }}`, database table please refer to here. Content block/Embed

## Example

- Query list items that contain `content block`:
  ```c3Fs
{{ SELECT * FROM blocks WHERE content LIKE '%content block%' AND type = 'i' }}
```
- The query content contains both `content block` and `reference` paragraph blocks:
  ```c3Fs
{{ SELECT * FROM blocks WHERE content LIKE '%content block%' AND content LIKE '%reference%' AND type = 'p') }}
```
- The query content contains heading blocks of both `content block` and `embed`, and the first 2 items are selected in descending order of update time:
  ```c3Fs
{{ SELECT * FROM blocks WHERE content LIKE '%content block%' AND content LIKE '%embed%' AND type ='h' ORDER BY updated DESC LIMIT 2 }}
```

### Case 1

The query contains paragraph blocks of both `In SiYuan` and `core concept` text, and excludes the current document (otherwise the paragraph block will also be included in the result set, because the current paragraph also contains these two texts. The following case is similar):

### Case 2

Query paragraph blocks that contain both tags `#Content block/Embed#` and `#Content block/Reference#`:

### Case 3

Sometimes we may need to randomly roam and display content blocks to facilitate review.

### Case 4

To query the unfinished task list items, you need to use the `markdown` field instead of the `content` field:

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-6yi0dv5/20201210233038-3xr19g5.sy -->

# Conversion of Document and Heading

## Correspondence between Document and Heading

The heading block and the document block have a natural correspondence, because:

- Each document block has a name
- Each heading block also has a name

So we can convert between the document block and the heading block. In addition, because the content block is referenced based on id, the conversion process will not break the existing reference relationship.

## Convert Document block to Heading block

In the doc tree, select the document that needs to be converted into a heading block, and then drag it to the position to be inserted in the editor tab. There are two situations here:

1. Place the document block on the existing heading block, and the document block will be inserted below as the level node of the heading block
2. Place the document block on a non-heading block, and the document block will be inserted as a child node of the heading block to which the block belongs

After the document block is converted to a heading block:

- The original document name will become the heading name
- Logically, the document block is a first-level title, and the relative level will be changed according to the insertion position
- Each heading level in the original document will be adjusted according to the insertion position
  - For the above situation 1: For example, if the original document contains the first, second, and third level headings, and the insertion position is a second-level heading, the heading block after the document block conversion will be a second-level heading. Level 3 headings will become Level 2, 3, and 4 headings
  - For the second case above: For example, the original document contains headings of level 1, 2, and 3, and the insertion position is a paragraph block under a level 2 heading. The heading block after the conversion of the document block will be a level 3 heading. Level 1, 2, and 3 headings will become Level 3, 4, and 5 headings

## Convert Heading block to Document block

In the editor tab, select the heading block to be converted, press and hold the heading block icon, and then drag it to the folder to be placed in the doc tree. If you need to place it on the notebook root folder, drag the heading block icon to the top notebook icon row.

After the heading block is converted to a document block:

- The heading name will become the document name
- If there are subtitles under the original heading block, the largest level of these subtitles will be used as the first level of the new document, and the remaining subtitles will be adjusted according to the relative level
  - For example, the original heading block contains three, four, and five levels of subtitles, and these subtitles will be converted into one, two, and three levels after being converted into a document block

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-6yi0dv5/20210613191509-cbkxcbz.sy -->

# Content Block Attribute

## Overview

Attributes exist in the form of key-value pairs. We can enrich the connotation of the content block by setting attributes on the content block. Attributes are divided into built-in attributes and custom attributes.

## Built-in attributes

| Property name | Description |
|---|---|
| name | Name of the content block |
| alias | Alias of content block |
| memo | Memo of the content block |
| bookmark | Bookmark of content block |

## Custom attributes

The user-defined attributes are set by the user through the `Block icon menu` -`Attribute`, and only English letters and Arabic numerals are allowed in the attribute name (such as `doing`, `7days`). After setting, SiYuan will automatically prefix the attribute name with `custom-` to distinguish built-in attributes from custom attributes.

## Using attributes

There are two main usage scenarios for attributes: querying content blocks based on attributes and storing widget data.

### Query content blocks based on attributes

For example, when we set the properties of `progress=30` and `priority=2` for the content block, we can query all content blocks with a progress of 30 and a priority of 2 through SQL:

```c3Fs
SELECT *
FROM blocks
WHERE id IN (
    SELECT block_id
    FROM attributes AS a
    WHERE (a.name ='custom-progress' AND a.value = '30')
       OR (a.name ='custom-priority' AND a.value = '2')
    GROUP BY block_id
    HAVING count(block_id) = 2
);
```

### Store widget data

The widget can set the attributes through the interface, please refer to the development document for details.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-6yi0dv5.sy -->

# Content Block

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-axh6q1d/20200924095938-a9p5450.sy -->

# Theme

## Installation

### Manual

1. Get the theme from somewhere and unzip it
2. <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Theme</kbd> - <kbd>Open the theme folder</kbd>
3. Copy the theme to this folder
4. Restart, select the desired theme in <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Theme</kbd>

### Community Bazaar

- In <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Theme</kbd> - <kbd>Bazaar</kbd>, browse online themes contributed by community developers
- Choose the required theme to install or update online

## Development

### Step

1. Give your subject a nice name, such as `alice`
2. <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Theme</kbd> - <kbd>Open theme folder</kbd>
3. Create a new folder `alice` in the opened folder, and create new `theme.css` and `theme.json` files in `alice`The `theme.json` file is as follows:
  ```anNvbg==
{
  "name": "midnight",
  "author": "Vanessa",
  "version": "1.0.0",
  "modes": ["dark"]
}
```
  `modes` is the appearance mode, divided into `dark` and `light`. Please modify the other fields as needed.
4. Open the `theme.css` file to start your coding journey
5. Restart, select the installed theme in <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Theme</kbd>

### Encoding

- Familiar with [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) basic knowledge
- Modify the color scheme in `:root{...}`. ⚠️ The variable items inherent in the official cannot be deleted
- Continue to modify according to steps 1-4 in the figure

- Copy and paste the modified content into `theme.css` and save
- Check the `Disable cache` in `Network` and run `window.location.reload()` to see the final result


In addition to modifying the style through theme.css, if theme.js exists in the theme folder, it will be automatically loaded when rendering the interface, so that some function-related customizations can be achieved through JavaScript code. Note: Do not modify the editor DOM, the blocks in the editor should pass the [Block API](https://github.com/siyuan-note/siyuan/blob/master/API.md#Blocks) to operate.

## Push to theme bazaar

Please make sure that the root path of your theme repository contains at least the following files before listing ([repo example](https://github.com/88250/Comfortably-Numb)):

- theme.css
- theme.json (please make sure the JSON format is correct)
- preview.png (please compress the image size within 512 KB)
- README.md (please note the case)

After confirmation, please [create a pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) to the [Community Bazaar](https://github.com/siyuan-note/bazaar) repository and modify the themes.json file in it. This file is the index of all community theme repositories, the format is:

```anNvbg==
{
   "repos": [
     "username/reponame@commithash"
   ]
}
```

Among them, `commithash`, please fill in the Git commit hash of the latest released version on your theme repository, please use the full hash value instead of the 7-digit short value.

### Update

If the theme you developed has an updated version, please remember:

- Update the version field in your theme.json
- Create a Pull Request to the community bazaar

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-axh6q1d/20200924100110-vcg96wy.sy -->

# Icon

## Installation

1. Get the icon and unzip
2. <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Icon</kbd> - <kbd>Open Icon Folder</kbd>
3. Copy the icon to this directory
4. Restart, select the installed icon in <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Icon</kbd>

## Development

### Step

1. Give your icon a nice name, such as `alice`
2. <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Icon</kbd> - <kbd>Open Icon Folder</kbd>
3. Create a new folder `alice` in the opened folder, and create new `icon.js` and `icon.json` files in `alice` The `icon.json` file is as follows:
  ```anNvbg==
{
  "name": "alice",
  "author": "Vanessa",
  "url": "https://github.com/Vanessa219",
  "version": "1.0.0"
}
```
4. Open the `icon.js` file and paste the completed icon
5. Restart, select the installed icon in <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Icon</kbd>

### Icon production

- Use a browser to open the `` file in the icon folder
- Make similar icons based on the icon name and shape
  - Go to [Iconfont](https://www.iconfont.cn) to search for your favorite icon and download the SVG format
  - Use vector graphics tools to make your own icons in SVG format
  - Go to [pngtosvg](https://www.pngtosvg.com/) to convert the picture to SVG format
- Go to [IcoMoon App](https://icomoon.io/app/#/select) to make ``
  - Click on `` in the upper right corner to import the pictures made in the previous step
  - Select the icon and generate SVG


  - Modify the size and download


  - Modify the `` in `` to the icon name corresponding to ``
  - Replace the content in `` to the corresponding position in ``
- Test
  - Replace `` in `` with ``
    ```aHRtbA==
<script src="material/icon.js"></script>
```
  - Refresh `` to see the final result
  - Open SiYuan and select the developed icon in <kbd>Settings</kbd> - <kbd>Appearance</kbd> - <kbd>Icon</kbd> to view

## Push to icon bazaar

Please make sure that the root path of your icon repository contains at least the following files before listing:

- icon.js
- icon.json (please make sure the JSON format is correct)
- preview.png (please compress the image size within 512 KB)
- README.md (please note the case)

After confirmation, please [create a pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) to the [Community Bazaar](https://github.com/siyuan-note/bazaar) repository and modify the consi.json file in it. This file is the index of all community icon repositories, the format is:

```anNvbg==
{
   "repos": [
     "username/reponame@commithash"
   ]
}
```

Among them, ``, please fill in the Git commit hash of the latest released version on your icon repository, please use the full hash value instead of the 7-digit short value.

### Update

If the icon you developed has an updated version, please remember:

- Update the version field in your icon.json
- Create a Pull Request to the community bazaar

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-axh6q1d.sy -->

# Custom Appearance

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-h361q1i/20200924093441-ft2rhps.sy -->

# Formatting elements

## Inline elements

- Please Start Here
- [Hyperlink](https://ld246.com)

- **Bold** 
- *Italic*
- Underline
- ~~Strikethrough~~ 
- ==Mark==
- Superscript
- Subscript
- <kbd>Keymap</kbd>
- Tag
- `Inline Code`
- **Color 1** **Color 2**  **Color 3** **Color 4** **Color 5** **Color 6** **Color 7** **Color 8** **Color 9** **Color 10** **Color 11** **Color 12** **Color 13**
  **Style 1** **Style 2**
- Trigger an emoji search by typing `:` followed by a letter 😄 😆 😵 😭 😰 😅 😢 😤 😍 😌👍 👎 💯 👏 🔔 🎁 ❓ 💣 ❤️ ☕️ 🌀 🙇 💋 🙏 💢

## Pictures

Support direct copy and paste or drag and upload. After uploading, you can adjust the size by dragging the sidebar.

## Super block

Paragraph 1

Paragraph 2 Center

Paragraph 3

Paragraph 4 Right

## Embed block

## Heading block

## Ordered, unordered, task list

### Unordered List

- Java
  - Spring
    - IoC
    - AOP
- Go
  - gofmt
  - Wide
- Node.js
  - KoaExpress
  - Express

### Ordered List

1. Node.js
  1. Express
  2. Koa
  3. Sails
2. Go
  1. gofmt
  2. Wide
3. Java
  1. Latke
  2. IDEA

### Task list

- Release SiYuan
- Book a dentist

## Blockquote

> Note that it is not a content block ref, but a block quote (Blockquote).

## Code block

If the language name is followed by ```, it can have the effect of syntax highlighting, for example:

### Demonstrate Go code highlighting

```Z28=
package main

import "fmt"

func main() {
fmt.Println("Hello, World")
}
```

### Demo Java highlighting

```amF2YQ==
public class HelloWorld {

    public static void main(String[] args) {
        System.out.println("Hello World!");
    }

}
```

> Tip: Language names support the following: `ruby`, `python`, `js`, `html`, `erb`, `css`, `coffee`, `bash`, `json`, `yml`, ` xml` ...

## Table

| header 1 | header 2 |
|---|---|
| cell 1 | cell 2 |
| cell 3 | cell 4 |
| cell 5 | cell 6 |

## HTML block

<ruby>
你<rt>nǐ</rt>
　好<rt>　hǎo</rt>
　世<rt>　shì</rt>
　界<rt>　jiè</rt>
</ruby><br>
Hello World

Note: The code in the HTML block will not be safely filtered when using it. Please confirm the code is safe before using it to avoid cross-site scripting (XSS).

## Horizontal rule

---

## Mathematical formula

$$
\frac{1}{
  \Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{
  \frac25 \pi}} = 1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {
    1+\frac{e^{-6\pi}}
    {1+\frac{e^{-8\pi}}{1+\cdots}}
  }
}
$$

## IFrame

## Video

## Audio

## Mind map

```bWluZG1hcA==
- Tutorial
- Grammar guidance
  - General content
  - Mention users
  - Emoji
    - Some emoji examples
  - Heading-Heading 3
    - Heading 4
      - Heading 5
        - Heading 6
  - Picture
  - Code block
    - Normal
    - Syntax highlighting support
      - Demonstrate Go code highlighting
      - Demo Java highlighting
  - Ordered, disordered, task list
    - Unordered list
    - Ordered list
    - task list
  - Form
  - Hide details
  - Paragraph
  - Link reference
  - Mathematical formula
  - Mind Map
  - Flow chart
  - Timing diagram
  - Gantt chart
  - Chart
  - Staff
  - Graphviz
  - Multimedia
  - Footnote
  - Shortcuts
```

Use Markdown list syntax to render the mind map.

## Flow chart

```bWVybWFpZA==
graph TB
    c1-->a2
    subgraph one
    a1-->a2
    end
    subgraph two
    b1-->b2
    end
    subgraph three
    c1-->c2
    end
```

Please refer to [Mermaid](https://github.com/mermaid-js/mermaid) for the syntax.

## Timing diagram

```bWVybWFpZA==
sequenceDiagram
    Alice->>John: Hello John, how are you?
    loop Every minute
        John-->>Alice: Great!
    end
```

Please refer to [Mermaid](https://github.com/mermaid-js/mermaid) for the syntax.

## Gantt chart

```bWVybWFpZA==
gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
    A task :a1, 2019-01-01, 30d
    Another task :after a1, 20d
    section Another
    Task in sec :2019-01-12, 12d
    another task: 24d```

Please refer to [Mermaid](https://github.com/mermaid-js/mermaid) for the syntax.

## Class diagram

```bWVybWFpZA==
classDiagram
Class01 &lt;|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --&gt; C2 : Where am i?
Class09 --* C3
Class09 --|&gt; Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 &lt;--&gt; C2: Cool label```

Please refer to [Mermaid](https://github.com/mermaid-js/mermaid) for the syntax.

## User Journey Diagram

```bWVybWFpZA==
journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me```

Please refer to [Mermaid](https://github.com/mermaid-js/mermaid) for the syntax.

## Git graph

```bWVybWFpZA==
gitGraph:
options
{
    &quot;nodeSpacing&quot;: 150,
    &quot;nodeRadius&quot;: 10
}
end
commit
branch newbranch
checkout newbranch
commit
commit
checkout master
commit
commit
merge newbranch```

Please refer to [Mermaid](https://github.com/mermaid-js/mermaid) for the syntax.

## Entity Relationship Diagram

```bWVybWFpZA==
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses```

Please refer to [Mermaid](https://github.com/mermaid-js/mermaid) for the syntax.

## Chart

```ZWNoYXJ0cw==
{
  "title": { "text": "Latest 30 days" },
  "tooltip": { "trigger": "axis", "axisPointer": { "lineStyle": { "width": 0 } } },
  "legend": { "data": ["Articles", "Users", "Replies"] },
  "xAxis": [{
      "type": "category",
      "boundaryGap": false,
      "data": ["2019-05-08","2019-05-09","2019-05-10","2019-05-11","2019-05-12","2019-05-13","2019-05-14","2019-05-15","2019-05-16","2019-05-17","2019-05-18","2019-05-19","2019-05-20","2019-05-21","2019-05-22","2019-05-23","2019-05-24","2019-05-25","2019-05-26","2019-05-27","2019-05-28","2019-05-29","2019-05-30","2019-05-31","2019-06-01","2019-06-02","2019-06-03","2019-06-04","2019-06-05","2019-06-06","2019-06-07"],
      "axisTick": { "show": false },
      "axisLine": { "show": false }
  }],
  "yAxis": [{ "type": "value", "axisTick": { "show": false }, "axisLine": { "show": false }, "splitLine": { "lineStyle": { "color": "rgba(0, 0, 0, .38)", "type": "dashed" } } }],
  "series": [
    {
      "name": "Articles", "type": "line", "smooth": true, "itemStyle": { "color": "#d23f31" }, "areaStyle": { "normal": {} }, "z": 3,
      "data": ["18","14","22","9","7","18","10","12","13","16","6","9","15","15","12","15","8","14","9","10","29","22","14","22","9","10","15","9","9","15","0"]
    },
    {
      "name": "Users", "type": "line", "smooth": true, "itemStyle": { "color": "#f1e05a" }, "areaStyle": { "normal": {} }, "z": 2,
      "data": ["31","33","30","23","16","29","23","37","41","29","16","13","39","23","38","136","89","35","22","50","57","47","36","59","14","23","46","44","51","43","0"]
    },
    {
      "name": "Replies", "type": "line", "smooth": true, "itemStyle": { "color": "#4285f4" }, "areaStyle": { "normal": {} }, "z": 1,
      "data": ["35","42","73","15","43","58","55","35","46","87","36","15","44","76","130","73","50","20","21","54","48","73","60","89","26","27","70","63","55","37","0"]
    }
  ]
}
```

## Staff

```YWJj
X: 24
T: Clouds Thicken
C: Paul Rosen
S: Copyright 2005, Paul Rosen
M: 6/8
L: 1/8
Q: 3/8=116
R: Creepy Jig
K: Em
|:"Em"EEE E2G|"C7"_B2A G2F|"Em"EEE E2G|\
"C7"_B2A "B7"=B3|"Em"EEE E2G|
"C7"_B2A G2F|"Em"GFE "D (Bm7)"F2D|\
1"Em"E3-E3:|2"Em"E3-E2B|:"Em"e2e gfe|
"G"g2ab3|"Em"gfeg2e|"D"fedB2A|"Em"e2e gfe|\
"G"g2ab3|"Em"gfe"D"f2d|"Em"e3-e3:|
```

Please refer to [abcjs](https://github.com/paulrosen/abcjs) for the syntax.

## Graphviz

```Z3JhcGh2aXo=
digraph finite_state_machine {
     rankdir=LR;
     size="8,5"
     node [shape = doublecircle]; S;
     node [shape = point ]; qi

     node [shape = circle];
     qi -> S;
     S -> q1 [label = "a" ];
     S -> S [label = "a" ];
     q1 -> S [label = "a" ];
     q1 -> q2 [label = "ddb" ];
     q2 -> q1 [label = "b" ];
     q2 -> q2 [label = "b" ];
}```

Please refer to [Graphviz](https://graphviz.org) for the syntax.

## Flowchart

```Zmxvd2NoYXJ0
st=>start: Start
op=>operation: Your Operation
cond=>condition: Yes or No?
e=>end

st->op->cond
cond(yes)->e
cond(no)->op
```

Please refer to [flowchart.js](https://github.com/adrai/flowchart.js) for the syntax.

## PlantUML

```cGxhbnR1bWw=
@startuml component
actor client
node app
database db
db -> app
app -> client
@enduml
```

Please refer to [PlantUML](https://plantuml.com) for the syntax.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-h361q1i.sy -->

# Editor

- Editing and typesetting based on content blocks
- List outline, support with or without sub-level indentation
- Content block zoom, that is, each content block can be zoomed into focus
- Dynamic loading, solving large document jams
- Horizontal layout by dragging block icon

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-l3qg72k/20201222100222-q47d64s.sy -->

# Type filtering

## Type field `type`

- `d` Document block (Only search on the document name, will not search for the document containing content blocks)
- `h` Heading block (Search only on the heading name, not the content blocks below the heading block)
- `l` List block (including ordered list block, unordered list block and task list block)
- `i` List item block
- `c` Code block
- `m` Mathematical formula block
- `t` Table block
- `b` Blockquote block
- `s` Super block
- `p` Paragraph block
- `html` HTML block

## Subtype field `subtype`

List block / List item block subtypes:

- `o`：Ordered
- `u`：Unordered
- `t`：Task

Heading subtypes:

- `h1`: Level 1
- `h2`: Level 2
- `h3`: Level 3
- `h4`: Level 4
- `h5`: Level 5
- `h6`: Level 6

Other types of content blocks have no subtypes.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-l3qg72k/20201222100339-i5hzcph.sy -->

# Database table

## Table `blocks`

This table is used to store content block data.

| Field | Description |
|---|---|
| id | Content block ID |
| parent_id | Parent block ID, If the content block is a document block, this field is empty |
| root_id | Root block ID, which is the document block ID |
| hash | Summary checksum of the content |
| box | Notebook ID |
| path | The path of the document where the content block is located |
| hpath | The path to the document where the human-readable content block is located |
| name | Content block name |
| alias | Content block alias |
| memo | Content block memo |
| content | Text with Markdown markers removed |
| fcontent | The first child block text with Markdown markers removed |
| markdown | Text with complete Markdown markers |
| length | Length of `fcontent` |
| type | Content block type, please refer to here |
| subtype | Content block subtype, please refer to here |
| ial | Inline attributes list, like  `{: name="value"}` |
| sort | For sorting, the smaller the value, the higher the sort |
| created | Create time |
| updated | Update time |

## Default values

- If `LIMIT` is not specified, only the first 64 results will be returned at most, adjustable via <kbd>Settings</kbd> - <kbd>Search</kbd> - <kbd>The number of search results displayed</kbd>
- `sort` field
  - Document block: `0`
  - Heading block: `5`
  - Paragraph block: `10`
  - Code block: `10`
  - Mathematical formula block: `10`
  - Table block: `10`
  - HTML block: `10`
  - List block: `20`
  - List item block: `20`
  - Blockquote block: `20`
  - Super block: `30`

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-l3qg72k/20220415232231-pqcizol.sy -->

# Query syntax

## Overview

Global search  <kbd>Ctrl+P</kbd> supports advanced search through query syntax, in order to implement some logical operations, such as the query syntax that contains the keyword `foo` and does not contain the keyword `bar` is `foo NOT bar`.

Before using the query syntax, let's have a general understanding of its composition:

- String: composed of letters, numbers, etc.
- Phrase: composed of strings
- Query: composed of phrases, multiple queries can be combined into a new query through `AND`, `OR` and `NOT`

Below we introduce their details respectively.

## Strings

Strings can be specified in two ways:

- Characters enclosed in English double quotes `"`. If `"` itself needs to be used, it can be escaped by SQL-style (plus a `"`), for example `"foo""bar"""` will hits `foo "bar"`
- Consists of non `AND`, `OR` and `NOT` characters, and these characters must be:
  - All non-ASCII characters, or
  - Belongs to 52 uppercase and lowercase English characters (`A-Za-z`), or
  - Belongs to 10 ASCII numeric characters (`0-9`), or
  - Is an underscore `_`, or
  - Is the replacement character (ASCII 26)

For strings that are not composed of other characters mentioned above, they must be wrapped with `"`, such as strings containing `-`, `*` and other symbols.

## Phrases

Phrases consist of strings, which can be concatenated by `+`. A phrase is composed of some tokens in order, and these tokens are processed by the user's input text through the tokenizer. The tokenizer used by SiYuan is to make Chinese search easy to use (supports single-word search), so the implementation is based on word segmentation ([Tokenizer code](https://github.com/siyuan-note/sqlite-fts5-siyuan-tokenizer)), which means that each Chinese character or English letter will be split into a token. This has some effect on `+` concatenation, so it is recommended not to use `+` to combine multiple phrases if unsure.

## Queries

A query consists of multiple phrases, which can be combined into a new query by the operators `AND`, `OR`, and `NOT`.

| Operator | Function |
|---|---|
| `<query1> AND <query2>` | Matches if both query1 and query2 match |
| `<query1> OR <query2>` | Matches if either query1 or query2 match |
| `<query1> NOT <query2>` | Matches if query1 matches and query2 does not match |

Use parentheses `()` to combine query priorities, for example:

```c3Fs
-- Matches documents that contain at least one instance of either "one" or "two", but do not contain any instances of token "three".
'one OR two NOT three'

-- Match all documents that contain the token "two" but not "three", or contain the token "one".
'one OR (two NOT three)'
```

Multiple phrases separated by spaces use `AND` by default, for example:

```c3Fs
'one two three'         -- 'one AND two AND three'
'three "one two"'       -- 'three AND "one two"'
'NEAR(one two) three'   -- 'NEAR(one two) AND three'
'one OR two three'      -- 'one OR two AND three'

'(one OR two) three'    -- Syntax error!
'func(one two)'         -- Syntax error!
```

## Technical implementation

We implement global search through [SQLite FTS5](https://www.sqlite.org/fts5.html).

The key part of the query statement generated by the system is roughly `MATCH '{content name alias memo}:" + query`, `query` is the user input part, for [column filter](https://www.sqlite.org/fts5 .html#fts5_column_filters) `{content name alias memo}:` is generated by <kbd>Settings</kbd> - <kbd>Search</kbd> - <kbd>Attribute</kbd>.

After knowing these, we can implement the query embedding block through the query syntax, so that the query performance will be better:

In addition to this, the API also supports querying using FTS.

### Case Sensitive

If the <kbd>Settings</kbd> - <kbd>Search</kbd> - <kbd>Case Sensitivity</kbd> option is enabled, the search will be case-sensitive. By default, this option is disabled, that is, insensitive upper and lower case.

Since the tokenizer is case-sensitive, we build two virtual tables to index separately:

- `blocks_fts`: word segmentation by character
- `blocks_fts_case_insensitive`: Convert English letters to lowercase participles

The disadvantage of this is that it increases disk space usage and reduces indexing performance, but there is currently no better solution, so it can only be done first. In addition, Unicode case folding and diacritics are not supported, only English letters are supported ignoring case.

If you have a better implementation, please let us know, thank you very much.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-l3qg72k.sy -->

# Advanced search

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-v9awwp0/20210721112159-9p645xm.sy -->

# Storage

The cloud storage space is `8G`, divided into three parts:

- Synchronized data: Provided to the synchronization function, the data is encrypted
- Backup data: Provided to the backup function, the data is encrypted
- Asset file: Provided for copying to the Wechat MP, Zhihu and Yuque, etc., HTTPS CDN

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-v9awwp0/20210721112206-mhr9wxi.sy -->

# Data Sync

## Overview

Data synchronization refers to keeping the `workspace/data/` folder data consistent on multiple devices, including asset files, templates, widgets, and notebook data.

## How to use

Open <kbd>Settings - Cloud - Cloud sync</kbd> and proceed through the synchronization setting wizard.

1. Set the end-to-end encryption password
2. Create or select a cloud synchronization directory. After selecting, the cloud synchronization directory will be used for data synchronization in the current workspace
3. Enable sync switch

Please perform the above operations on the *main* device first, then select the same cloud sync directory on other devices and turn on the sync switch. If you want to switch, rename or remove the cloud sync directory, please turn off the sync switch on all devices before proceeding.

## Ignore files

If you need to ignore some files during synchronization, please create or edit the text file `workspace/data/.siyuan/syncignore` on the file system, each line is configured with the relative path of the data folder, which means that the path of the file or folder is ignored and wildcard characters are supported. E.g:

- `20210808180117-6v0mkxr/**/*`: Ignore the data/20210808180117-6v0mkxr notebook
- `assets/*.pdf`: ignore PDF files under data/assets/

## Working principle

SiYuan performs corresponding operations by comparing the cloud data version and the local data version:

- Skip if the version is equal
- If the cloud version is greater than the local version, download the cloud data locally and decrypt it to the `workspace/data/` folder, and the local overwritten or deleted files will be moved to the `workspace/history/` folder
- If the cloud version is less than the local version, scan for changes in `/workspace/data/`, then encrypt the changes and copy them to the folder `workspace/sync/`, and finally upload and overwrite the cloud data

The version comparison is automatically performed at regular intervals. The time interval algorithm is described as follows:

- After 30 seconds of data change, if there is no further change, a comparison will be made, and if it continues to change, it will be delayed by 30 seconds
- If there is no data change, it will be incremented by 5 minutes, 8 minutes, 16 minutes, 32 minutes...

## Scenario example

From the above working principle, we can know that SiYuan only supports alternate synchronization of data on multiple devices: after synchronization is completed on device A, synchronization is performed on device B. Simultaneous synchronization of multiple devices cannot be supported, so unexpected data overwriting will occur.

### Normal scene

1. Execute synchronization after editing on device A (by triggering synchronization automatically or manually), at this time, the cloud data will be overwritten by the data of device A, that is, the cloud and device A keep the same data
2. Execute synchronization on device B. At this time, the data of device B will be overwritten by the cloud data, that is, the cloud and devices A and B keep the same data
3. After editing on device B, perform synchronization again. At this time, the cloud data will be overwritten by device B data, that is, the cloud and device B keep the same data.
4. Execute synchronization on device A. At this time, the data of device A will be overwritten by the cloud data, that is, the cloud and devices A and B keep the same data

In this scenario, the process of using synchronization is performed alternately on devices A and B, which can ensure that data synchronization is completed normally as expected.

### Override scene

1. Not syncing after editing on device A (for example, when there is no network and it is offline)
2. Not syncing after editing on device B
3. Perform synchronization on device A. At this time, the cloud data will be overwritten by the data of device A, that is, the cloud and device A keep the same data.
4. Perform a sync on device B, at which point there are three possible scenarios
  - Device B data skip synchronization because the version and cloud are the same
  - Device B data covers the cloud
  - Device B data is overwritten by the cloud

In this scenario, the process of using synchronization is to edit offline on both devices, and then perform synchronization, so that the expected results of normal synchronization cannot be obtained. Even so, the data will not be lost, and the overwritten data can be retrieved through history.

## Note

- Synchronization will not be triggered in the case of sudden disconnection such as sleep or shutdown, please manually click the synchronization button to synchronize
- Before renaming or deleting the cloud directory, please turn off synchronization on all devices before editing or deleting
- Do not use a third-party sync disk and SiYuan sync at the same time, it may cause data damage
- Symbolic links will not be synchronized

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-v9awwp0/20210721112211-fwc1x43.sy -->

# Data Backup

## Backup

Backup refers to encrypting and copying all files in the `workspace/data/` folder to the `workspace/backup/` folder.

### How to use

1. Open <kbd>Settings - Cloud</kbd>, configure <kbd>End-to-end encryption password</kbd>
2. <kbd>Settings - Cloud - Local backup</kbd> select <kbd>Backup and upload</kbd>, after the backup is completed, a popup will prompt whether to upload, select <kbd>Confirm</kbd>
3. After the upload is complete, there will be a copy of the same encrypted data as the local backup in the cloud

## Recovery

Restoration refers to restoring the encrypted data in the `workspace/backup/` folder to the `workspace/data/` folder.

### How to use

1. Open <kbd>Settings - Cloud</kbd>, configure <kbd>End-to-end encryption password</kbd>
2. <kbd>Settings - Cloud - Cloud backup</kbd> Select <kbd>Download and recover</kbd>, after the download is complete, a pop-up will prompt whether to restore, select <kbd>Confirm</kbd>
3. After the recovery is complete, the application will be closed, and you can restart it manually

## Note

- The backup data is stored in the `workspace/backup/` folder by default, and the location can be modified
- Do not use a third-party synchronization disk to synchronize the folder, otherwise it may cause data damage
- Without changing the password, the data is transferred incrementally
- The password must be kept in mind, the data cannot be recovered without a password, and the password cannot be cleared or retrieved
- After restoring from the backup, the current workspace data will be overwritten and cannot be restored. Please confirm before using the backup to restore

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-v9awwp0/20210721112229-fp97j3c.sy -->

# End-to-end Encryption

## Overview

SiYuan will encrypt data before backup and synchronization, and the encrypted data can be safely transmitted and hosted over the network.

- The encryption and decryption process is completely performed on the local device
- The encryption algorithm is AES GCM, which is recognized as safe in the industry
- The password set by the user is encrypted with the built-in key of the program and stored locally

## Password generation

There are two methods to generate end-to-end encrypted passwords:

1. Automatic generation of algorithm based on user id
2. Based on user-defined password generation

The differences between the two password generation methods are:

- The id generation method is mainly for simplicity and convenience, but technically developers can decrypt data in the cloud
- The main purpose of using a custom password is to be more secure (unless you know the password or brute force, it cannot be decrypted), but the operation is relatively troublesome and the password must be remembered

## Note

Once the password generation method is selected:

- Need to keep the same build method on all devices
- You cannot switch after selecting the generation method
- If you use a custom password, please keep in mind

## Encrypted content

data/.siyuan folder and sub-files conf.json, syncignore, these data are configuration and metadata required for synchronization, so they will not be encrypted.

In addition to this, all data in the data folder will be encrypted. The specific encrypted content is:

- Folder name and file name (such as the file name of .sy files and assets files)
- file content

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-v9awwp0/20210721160238-yvhbh0h.sy -->

# Assets Serving

SiYuan provides cloud assets serving, which is mainly used to copy documents and asset files to platforms such as WeChat MP, Zhihu and Yuque. The editors of these platforms will automatically pull resource files to their platforms when pasting.

## How to use

1. In the upper right corner of the document, select <kbd>...</kbd> in the More menu and select <kbd>Upload asset files to cloud</kbd>
2. Select <kbd>Export Preview</kbd> in <kbd>Toogle Mode</kbd>
3. Click <kbd>Copy to Wechat MP</kbd>, <kbd>Copy to Zhihu</kbd> or <kbd>Copy to Yuque</kbd>
4. Paste into the target platform editor

If you need to delete the files in the cloud assets serving, please go to [LianDi - Settings - File - Note](https://ld246.com/settings/file?type=3) to operate. After deletion, the cloud storage space occupied by the file will be released immediately, but the CDN cache cleaning may not take effect in time, which will cause the file URL to remain accessible until the CDN cache expires automatically after 30 days.

## Note

- Please do not directly use the external link address provided by cloud assets on other platforms. This address is unstable and may affect the availability due to the domain name change
- Please do not upload illegal or sensitive files. The uploaded files will be reviewed through services provided by third parties (pornography, violent terrorism, sensitive people, etc.). If a user is found to upload illegal files, the user account will be permanently banned, and the corresponding legal responsibility will be assumed

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-v9awwp0/20220105101227-n5zpr1a.sy -->

# Limitations

- During synchronization or backup, single file transfer larger than 100MB is not supported
- Supports the creation of up to 7 cloud synchronization directories
- The initial total size of cloud storage space is `8G`
- After the paid subscription expires, the cloud storage will be completely deleted

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-v9awwp0.sy -->

# Cloud

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20200924100635-ms0p9lb.sy -->

# Bookmark and Tag

## Bookmark

If you need to "favorite" content blocks, please open the attribute panel through the block icon menu, and then you can set bookmarks in the attribute panel.

The built-in bookmark label are ✨💡️⏳, you can create other text as the bookmark label.

All favorite content blocks will be listed in the bookmark tab (<kbd>Alt 3</kbd> / <kbd>⌘ 3</kbd>). If you want to cancel the collection, select Delete in the drop-down menu of the content block ID.

## Tag

The tag is used to mark the block in the content block. The syntax is to wrap the tag identifier with two `#` in the first and one after the other, like this `#Tag#`.

Tag support hierarchical levels, so that content blocks can be sorted more easily. Use `/` to separate different levels, like this `#A/B/C#`.

All tagged content blocks will be listed in the tag tab (<kbd>Alt 4</kbd> / <kbd>⌘ 4</kbd>). If you need to cancel the tag, just delete the tag in the content block.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20200924100717-yzwzn64.sy -->

# Kernel parameter

### `--workspace`

Used to specify the workspace folder path, the default value when not specified is `~/Documents/SiYuan/`.

### `--wd`

Kernel working directory path, automatically obtained according to the kernel executable file entry if it is not specified.

### `--resident`

After specifying with `--resident=true`, the kernel will be resident in memory, the default is `true`.

After set to `false`, the list of active sessions will be checked every 30 seconds, and the kernel process will be exited if there are no active sessions.

### `--readonly`

After specifying with `--readonly=true`, the kernel will run in read-only mode and all write operations will be prohibited.

### `--accessAuthCode`

Used to specify the browser access authentication password, which will overwrite the authCode in conf.json after setting.

### `--ssl`

After using `--ssl=true`, https and wss protocols will be used for serving.

### `--lang`

Using `--lang=zh_CN` will use Simplified Chinese to initialize the appearance language, the default is `en_US`. Currently available values: `zh_CN`, `zh_CHT`, `en_US` and `fr_FR`.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20200924100744-br924ar.sy -->

# Assets

## Overview

Attachments inserted through the editor will be regarded as asset files and will be placed in the workspace data/assets folder by default.

## Insert picture

In the editor, you can directly paste the copied picture from the system clipboard, or you can also insert pictures by dragging and dropping picture files into the editor.

If you specify a title for a picture, then the title will be rendered below the image as a legend.

## Cleanup unreferenced assets

"Reference" refers to the link `[foo](bar)` through Markdown, the image syntax `![foo](bar)` or the attribute `src` of HTML tags (such as `<img>`, `<iframe>`) link the asset files. There are two situations:

1. Reference to a specific asset file, such as a picture or a file
2. Reference to a asset folder (a subfolder under the assets folder) must end with `/`, such as `[foo](assets/bar/)`

The second case is special: if a asset folder is referenced, all the following asset files will be counted as already referenced regardless of whether they are individually referenced.

In <kbd>Settings</kbd> - <kbd>Assets</kbd>, you can clean up unreferenced assets by one-click. If you need to retrieve files that have been deleted by mistake, please via Rollback.

Note: Using absolute paths (local or network paths) will not be included Clean up calculations.

## Notebook-level assets

If you need to place the inserted assets in the assets folder at the same level as the document by default, you need to manually create a folder named assets first, so that SiYuan will preferentially select the assets folder to store the assets.

It is recommended not to use notebook-level assets as much as possible, as this has some side effects:

- When deleting the notebook, in order to ensure that cross-notebook asset references work properly, the assets under the notebook will be copied to the global assets in batches
- Does not support viewing notebook-level assets history in data history

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20200924100808-j9sddk9.sy -->

# Import and Export

## Import

### Markdown

SiYuan supports importing Markdown files. So if you need to import data from other note-taking software, please convert the data into Markdown files first.

If the image syntax (local relative path) like `![foo](images/bar.png)` is encountered during import, SiYuan will convert `images/bar.png` into assets. But if it is `.images/bar.png`, it will not be converted, because the path files starting with `.` are hidden files, SiYuan will not process them.

### Data

You can import and export data in <kbd>Settings</kbd> - <kbd>Export</kbd> on the desktop-end and <kbd>About</kbd> on the right sidebar on the mobile-end. The export here will completely copy and pack the `workspace/data/` folder into a zip archive.

The <kbd>Import Data</kbd> function only supports processing the data archive exported in the above steps. The import is copied to the current `workspace/data/` folder according to the file path in the archive:

- Duplicate files are overwritten
- Add files that do not exist
- Do not do any processing for existing files

Note: Please pay attention before use, to avoid existing data being overwritten and unrecoverable.

## Export

### Edit content copy

After selecting the content, use the copy shortcut <kbd>Ctrl+C</kbd>, and the clipboard is standard Markdown text.

If you need to copy HTML content, please switch to <kbd>Export Preview</kbd> from <kbd>Toogle Mode</kbd> in the <kbd>...</kbd> menu in the upper right corner of the editor tab before copying.

### Full text export

After selecting the document on the document tree, right-click and select <kbd>Export</kbd> or select <kbd>Export</kbd> from the <kbd>...</kbd> menu in the upper right corner of the editor tab:

- Markdown
- PDF
- HTML
- Word .docx

There are some options in <kbd>Settings</kbd> - <kbd>Export</kbd> to configure export processing, please refer to the prompt information on this interface for details.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20200924100906-0u4zfq3.sy -->

# Window and Tab

SiYuan supports multiple windows and multiple tabs, so that you can edit and view documents easily.

The tabs support up and down and left and right split screens, and all open tabs are synchronized in real time. For example, if you open multiple tabs for the same document, after editing and saving one of the tabs, the other tabs will also automatically synchronize the latest content to avoid dirty data overwriting while enjoying the convenience of multiple openings.

Except that the document is saved synchronously, the associated rendering generated after saving is also synchronous. The preview of the content block and the relationship diagram related to the document are refreshed in real time, which can eliminate interference to the minimum and let us focus on the notebook.

In addition to split-screen operation, the tabs also support drag and drop, so that we can arrange the entire interface as we want, record notes and organize knowledge in our most comfortable layout.

If the screen of the device you are using is small, you can consider use on browser, so that you can switch the interface through the browser instance.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20200924100950-9op5xi1.sy -->

# Shortcuts

## General

| Name | Shortcuts | Memo |
|---|---|---|
| New doc | <kbd>Ctrl+N</kbd> / <kbd>⌘N</kbd> |  |
| Global search | <kbd>Ctrl+P</kbd> / <kbd>⌘P</kbd> |  |
| Search | <kbd>Ctrl+F</kbd> / <kbd>⌘F</kbd> |  |
| Replace | <kbd>Ctrl+R</kbd> / <kbd>⌘R</kbd> |  |
| Close tab | <kbd>Ctrl+W</kbd> / <kbd>⌘W</kbd> |  |
| Select next tab | <kbd>Ctrl+Tab</kbd> / <kbd>⌃Tab</kbd> |  |
| Select previous tab | <kbd>Ctrl+Shift+Tab</kbd> / <kbd>⌃⇧Tab</kbd> |  |
| Doc tree tab | <kbd>Alt+1</kbd> / <kbd>⌥1</kbd> |  |
| Linkage outline tab | <kbd>Alt+2</kbd> / <kbd>⌥2</kbd> |  |
| Bookmark tab | <kbd>Alt+3</kbd> / <kbd>⌥3</kbd> |  |
| Tag tab | <kbd>Alt+4</kbd> / <kbd>⌥4</kbd> |  |
| Daily notes | <kbd>Alt+5</kbd> / <kbd>⌥5</kbd> |  |
| Linkage backlink tab | <kbd>Alt+7</kbd> / <kbd>⌥7</kbd> |  |
| Linkage graph tab | <kbd>Alt+8</kbd> / <kbd>⌥8</kbd> |  |
| Global graph tab | <kbd>Alt+9</kbd> / <kbd>⌥9</kbd> |  |
| Settings | <kbd>Alt+P</kbd> / <kbd>⌥P</kbd> |  |
| Page reset | <kbd>Ctrl+0</kbd> / <kbd>⌘0</kbd> |  |
| Page zoom in | <kbd>Ctrl+=</kbd> / <kbd>⌘=</kbd> |  |
| Page zoom out | <kbd>Ctrl+-</kbd> / <kbd>⌘-</kbd> |  |
| Hide/show window | <kbd>Alt+M</kbd> / <kbd>⌥M</kbd> |  |
| Lock screen | <kbd>Alt+N</kbd> / <kbd>⌥N</kbd> |  |
| Select up and down | <kbd>↑</kbd> / <kbd>↓</kbd> | When the prompt list appears, you can select up and down |
| Complete selection | <kbd>Enter</kbd> | Use the highlighted content in the list to complete |
| Move doc | - | Go to Settings -> Shortcuts to configure |

## Doc tree

| Name | Shortcuts | Memo |
|---|---|---|
| Context menu | <kbd>Ctrl+/</kbd> |  |
| Choose | <kbd>↑</kbd> / <kbd>↓</kbd> / <kbd>→</kbd> / <kbd>←</kbd> |  |
| Open | <kbd>Enter</kbd> |  |
| Delete | <kbd>Delete</kbd> |  |
| Search | <kbd>Ctrl+F</kbd> / <kbd>⌘F</kbd> |  |
| Rename | <kbd>F2</kbd> |  |
| Move doc | - | Go to <kbd>Settings - Shortcuts</kbd> to configure |

## Editor

### General

| Name | Shortcuts | Memo |
|---|---|---|
| Select All | <kbd>Ctrl+A</kbd> / <kbd>⌘A</kbd> | In the code block, only select the content of the code block |
| Global search | <kbd>Ctrl+Shift+F</kbd> / <kbd>⇧⌘F</kbd> / <kbd>Click+Tag</kbd> |  |
| Cut/cut block content | <kbd>Ctrl+X</kbd> / <kbd>⌘X</kbd> | Cut block content when no content is selected |
| Copy | <kbd>Ctrl+C</kbd> / <kbd>⌘C</kbd> | Copy block content when no content is selected |
| Copy block hyperlink | <kbd>Ctrl+Shift+H</kbd> / <kbd>⇧⌘H</kbd> |  |
| Copy block embed | <kbd>Ctrl+Shift+E</kbd> / <kbd>⇧⌘E</kbd> |  |
| Copy block reference | <kbd>Ctrl+Shift+C</kbd> / <kbd>⇧⌘C</kbd> |  |
| Paste | <kbd>Ctrl+V</kbd> / <kbd>⌘V</kbd> | The selected content can be used as link text or block ref anchor |
| Paste as plain text | <kbd>Ctrl+Shift+V</kbd> / <kbd>⇧⌘V</kbd> | Available on desktop only |
| Block attribute | <kbd>Ctrl+Alt+A</kbd> / <kbd>⌥⌘A</kbd> |  |
| Revoke | <kbd>Ctrl+Z</kbd> / <kbd>⌘Z</kbd> |  |
| Redo | <kbd>Ctrl+Y</kbd> / <kbd>⌘Y</kbd> |  |
| Rename | <kbd>F2</kbd> |  |
| Use the selection as the name of the new document | <kbd>F3</kbd> |  |
| Use the selection/block as the content of the new document | <kbd>F4</kbd> |  |
| Refresh current editor | <kbd>F5</kbd> |  |
| Open file location | <kbd>Alt+A</kbd> / <kbd>⌥A</kbd> |  |
| Outline | <kbd>Alt+O</kbd> / <kbd>⌥O</kbd> |  |
| Backlink | <kbd>Alt+B</kbd> / <kbd>⌥B</kbd> |  |
| Graph | <kbd>Alt+G</kbd> / <kbd>⌥G</kbd> |  |
| History | <kbd>Alt+H</kbd> / <kbd>⌥H</kbd> |  |
| Full screen | <kbd>Alt+Y</kbd> / <kbd>⌥Y</kbd> |  |
| Left | <kbd>Alt+L</kbd> / <kbd>⌥L</kbd> |  |
| Center | <kbd>Alt+C</kbd> / <kbd>⌥C</kbd> |  |
| Right | <kbd>Alt+R</kbd> / <kbd>⌥R</kbd> |  |
| Switch to Instant Rendering mode | <kbd>Ctrl+Alt+7</kbd> / <kbd>⌥⌘7</kbd> |  |
| Switch to Preview mode | <kbd>Ctrl+Alt+9</kbd> / <kbd>⌥⌘9</kbd> |  |
| Insert an empty block before the block | <kbd>Ctrl+Shift+B</kbd> / <kbd>⇧⌘B</kbd> |  |
| Insert an empty block after the block | <kbd>Ctrl+Shift+A</kbd> / <kbd>⇧⌘A</kbd> |  |
| Move up the block | <kbd>Ctrl+Shift+↑</kbd> / <kbd>⇧⌘↑</kbd> |  |
| Move down the block | <kbd>Ctrl+Shift+↓</kbd> / <kbd>⇧⌘↓</kbd> |  |
| Select the content from the beginning of the line to the cursor | <kbd>Shift+Home</kbd> / <kbd>⇧⌘←</kbd> |  |
| Select the content from the cursor to the end of the line | <kbd>Shift+End</kbd> / <kbd>⇧⌘→</kbd> |  |
| Select the content from the beginning of the block to the cursor | <kbd>⇧Home</kbd> | macOS only |
| Select the content from the cursor to the end of the block | <kbd>⇧End</kbd> | macOS only |
| Move the cursor to the beginning of the line | <kbd>Home</kbd> / <kbd>⌘←</kbd> |  |
| Move the cursor to the end of the line | <kbd>End</kbd> / <kbd>⌘→</kbd> |  |
| Move the cursor to the beginning of the block | <kbd>Home</kbd> | macOS only |
| Move the cursor to the end of the block | <kbd>End</kbd> | macOS only |
| Scroll to the top | <kbd>Ctrl+Home</kbd> / <kbd>⌘Home</kbd> |  |
| Scroll to the bottom | <kbd>Ctrl+End</kbd> / <kbd>⌘End</kbd> |  |
| Scroll up one screen | <kbd>PageUp</kbd> |  |
| Scroll down one screen | <kbd>PageDown</kbd> |  |
| Select one by one to the left | <kbd>Shift+←</kbd> / <kbd>⇧←</kbd> |  |
| Select one by one to the right | <kbd>Shift+→</kbd> / <kbd>⇧→</kbd> |  |
| Select block elements upward in turn | <kbd>Shift+↑</kbd> / <kbd>⇧↑</kbd> |  |
| Select block elements in turn | <kbd>Shift+↓</kbd> / <kbd>⇧↓</kbd> |  |
| Collapse/Expand | <kbd>Ctrl+↑</kbd> / <kbd>⌘↑</kbd> |  |
| Expand | <kbd>Ctrl+↓</kbd> / <kbd>⌘↓</kbd> |  |
| Zoom in | <kbd>Alt+→</kbd> / <kbd>⌥→</kbd> |  |
| Zoom out | <kbd>Alt+←</kbd> / <kbd>⌥←</kbd> |  |
| Select multiple blocks | <kbd>Shift+Click</kbd> / <kbd>⇧Click</kbd> |  |
| Delete | <kbd>Backspace</kbd> |  |
| Ref content block | <kbd>((</kbd> / <kbd>[[</kbd> / <kbd>Ctrl+[</kbd> / <kbd>⌘[</kbd> | <kbd>Ctrl+[</kbd> / <kbd>⌘[</kbd> Text content needs to be selected |
| Open the ref block by popover | <kbd>Ctrl+Alt+.</kbd> / <kbd>⌥⌘.</kbd> |  |
| Open the ref block in a new tab | <kbd>Ctrl+Shift+></kbd> / <kbd>⇧⌘.</kbd> |  |
| Open the ref block on the right | <kbd>Alt+.</kbd> / <kbd>⌥.</kbd> |  |
| Open the ref block on the bottom | <kbd>Shift+></kbd> / <kbd>⇧></kbd> |  |
| Embed content block | <kbd>{{</kbd> |  |
| Call up the function menu | <kbd>/</kbd> |  |
| Call up the block menu | <kbd>Ctrl+/</kbd> / <kbd>⌘/</kbd> |  |

### Block icon

| Name | 操作 |
|---|---|
| Move | Drag and drop |
| Open the menu | <kbd>Click</kbd> |
| Zoom in | <kbd>Ctrl+Click</kbd> / <kbd>⌘Click</kbd> |
| Collapse/Expand | <kbd>Alt+Click</kbd> / <kbd>⌥Click</kbd> |
| Naming | <kbd>Shift+Click</kbd> / <kbd>⇧Click</kbd> |

### Insert element

| Name | Shortcuts | Memo |
|---|---|---|
| Emoji | <kbd>:</kbd> |  |
| Block Ref | <kbd>Alt+[</kbd> / <kbd>⌥[</kbd> | Must select content |
| Bold | <kbd>Ctrl+B</kbd> / <kbd>⌘B</kbd> |  |
| Italic | <kbd>Ctrl+I</kbd> / <kbd>⌘I</kbd> |  |
| Mark | <kbd>Ctrl+E</kbd> / <kbd>⌘E</kbd> |  |
| Tag | <kbd>Ctrl+T</kbd> / <kbd>⌘T</kbd> |  |
| Strikethrough | <kbd>Ctrl+D</kbd> / <kbd>⌘D</kbd> |  |
| Superscript | <kbd>Ctrl+H</kbd> / <kbd>⌘H</kbd> |  |
| Subscript | <kbd>Ctrl+J</kbd> / <kbd>⌘J</kbd> |  |
| Keyboard | <kbd>Ctrl+'</kbd> / <kbd>⌘'</kbd> |  |
| Underline | <kbd>Ctrl+U</kbd> / <kbd>⌘U</kbd> |  |
| Inline math | <kbd>Ctrl+M</kbd> / <kbd>⌘M</kbd> |  |
| Dividing line | <kbd>---</kbd> |  |
| Code | <kbd>Ctrl+G</kbd> / <kbd>⌘G</kbd> |  |
| Blockquote | <kbd>></kbd> |  |
| Link | <kbd>Ctrl+K</kbd> / <kbd>⌘K</kbd> |  |
| Font setting | <kbd>Ctrl+Alt+X</kbd> / <kbd>⌥⌘X</kbd> |  |
| Recently used fonts | <kbd>Alt+X</kbd> / <kbd>⌥X</kbd> |  |
| Code block | <kbd>Enter```</kbd> / <kbd>Ctrl+Shift+K</kbd> / <kbd>⇧⌘K</kbd> |  |
| Unordered list | <kbd>* </kbd> | See below for related shortcuts |
| Ordered list | <kbd>1. </kbd> | See below for related shortcuts |
| Task list | <kbd>Ctrl+L</kbd> / <kbd>⌘L</kbd> / <kbd>[]</kbd> | See below for related shortcuts |
| Table | <kbd>Ctrl+O</kbd> / <kbd>⌘O</kbd> | See below for related shortcuts |

### Heading

| Name | Shortcuts |
|---|---|
| Level 1 heading | <kbd>Ctrl+Alt+1</kbd> / <kbd>⌥⌘1</kbd> |
| Level 2 heading | <kbd>Ctrl+Alt+2</kbd> / <kbd>⌥⌘2</kbd> |
| Level 3 heading | <kbd>Ctrl+Alt+3</kbd> / <kbd>⌥⌘3</kbd> |
| Level 4 heading | <kbd>Ctrl+Alt+4</kbd> / <kbd>⌥⌘4</kbd> |
| Level 5 heading | <kbd>Ctrl+Alt+5</kbd> / <kbd>⌥⌘5</kbd> |
| Level 6 heading | <kbd>Ctrl+Alt+6</kbd> / <kbd>⌥⌘6</kbd> |

### List

| Name | Shortcuts | Memo |
|---|---|---|
| Indent with sublists | <kbd>Tab</kbd> |  |
| Reverse indent 1 | <kbd>Shift+Tab</kbd> / <kbd>⇧Tab</kbd> |  |
| Reverse indent 2 | <kbd>Delete</kbd> | Beginning of the line |
| Switch between Done and To Do | <kbd>Ctrl+Enter</kbd> / <kbd>⌘Enter</kbd> / <kbd>click</kbd> | Task list |

### Table <kbd>Ctrl+Shift+M</kbd> / <kbd>⇧⌘M</kbd>

| Name | Shortcuts |
|---|---|
| Insert a row above | <kbd>Ctrl+Shift+T</kbd> / <kbd>⇧⌘T</kbd> |
| Insert a row below | <kbd>Ctrl+Shift+D</kbd> / <kbd>⇧⌘D</kbd> |
| Insert a column on the left | <kbd>Ctrl+Shift+L</kbd> / <kbd>⇧⌘L</kbd> |
| Insert a column on the right | <kbd>Ctrl+Shift+R</kbd> / <kbd>⇧⌘R</kbd> |
| Move row to up | <kbd>Ctrl+Alt+T</kbd> / <kbd>⌥⌘T</kbd> |
| Move row to down | <kbd>Ctrl+Alt+B</kbd> / <kbd>⌥⌘B</kbd> |
| Move column to left | <kbd>Ctrl+Alt+L</kbd> / <kbd>⌥⌘L</kbd> |
| Move column to right | <kbd>Ctrl+Alt+R</kbd> / <kbd>⌥⌘R</kbd> |
| Delete row | <kbd>Ctrl+-</kbd> / <kbd>⌘-</kbd> |
| Delete column | <kbd>Ctrl+Shift+_</kbd> / <kbd>⇧⌘-</kbd> |
| Move the cursor to the previous element | <kbd>Shift+Tab</kbd> / <kbd>⇧⇥</kbd> |
| Move the cursor to the next element | <kbd>Tab</kbd> / <kbd>⇥</kbd> |

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20201004194026-s8h2cog.sy -->

# Use on browser

## Browser usage

SiYuan Desktop is an standalone application packaged based on [Electron](https://www.electronjs.org), but this is not the only way to use it. As long as the kernel of SiYuan is started, it can be used directly on the browser, supporting mobile browsers.

- Desktop Web version: the experience is almost the same as the Electron standalone application
- Mobile Web version: specially designed for mobile-end user experience

After visiting `http://127.0.0.1:6806/`, the desktop or mobile version will be automatically switched according to the browser version.

If you need to use it in a local area network, just replace `127.0.0.1` with the local area network IP address. In addition to local LAN use, here are two self-service solutions for public network use:

- Publish local kernel services on the public network through the "intranet penetration" technology (more troublesome and unstable, not recommended)
- Build your own SiYuanServer (recommended)

Before embarking on these two solutions, please start with understanding [SiYuan Technical Architecture](https://ld246.com/article/1619868273581#%E6%8A%80%E6%9C%AF%E6%9E%B6%E6%9E%84).

### Access authentication

In <kbd>Settings</kbd> - <kbd>About</kbd>, you can configure the browser access authentication password. Leaving it blank means that authentication is not enabled. This is more useful in open networks (such as office spaces and public networks), and only after authentication can you enter the work space.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20201204184532-3qm9l8n.sy -->

# Template snippet

## Overview

The template snippet is used to quickly insert the previously set text content at the cursor caret position, and it supports variables. Template snippets use `.md` suffix files and are stored in the data/templates folder of the workspace.

## Writing a template

The template is implemented using [The Go Programming Language text template](https://golang.org/pkg/text/template/). If you have an understanding of this, you can implement some program logic in it, such as comparison logic , Iterative logic, etc. In addition, to avoid syntax conflicts, template syntax uses `.action{action}` (instead of `{{action}}`).

We have built-in variables and functions to enrich the template through the open source project [Sprig](https://github.com/Masterminds/sprig). For example, you can use `.action{now | date "2006-01-02 15:04:05"}` to render the current time. For more usage, please refer to [Sprig Function Documentation](http://masterminds.github.io/sprig/).

There is a detail about the date and time formatting. Note: The formatting of the Go programming language is quite special: Instead of using `yyyy-MM-dd HH:mm:ss`, use `2006-01-02 15:04: 05` This fixed time format ([related discussions on Stack Overflow](https://stackoverflow.com/questions/20530327/origin-of-mon-jan-2-150405-mst-2006-in-golang)).

In addition to the built-in variables and functions of Sprig, the following variables and functions are also supported:

- `title`: Use this variable to insert the current document name. For example, if the template content is `# .action{.title}`, it will be inserted into the current document content with the first-level heading syntax after invoking
- `id`：Use this variable to insert the current document id
- `name`: Use this variable to insert the current document name
- `alias`：Use this variable to insert the current document alias
- `queryBlocks`: This function is used to query the database, and the return value is a list of blocks,  and the parameter is a SQL statement: `.action{sql "SELECT * FROM blocks LIMIT 7"}`
- `querySpans`: This function is used to query the database, and the return value is a list of spans,  and the parameter is a SQL statement: `.action{sql "SELECT * FROM spans LIMIT 7"}`
- `parseTime`: This function is used to parse a string in time format into a `time.Time` type so that more formatting methods can be used to render the time

`queryBlocks` and `querySpans` support variable parameter lists similar to SQL prepared statements to facilitate the input of parameters:

```
.action{$today := now | date "20060102150405"}
.action{$blocks :=queryBlocks "SELECT * FROM blocks WHERE content LIKE '?' AND updated > '?' LIMIT ?" "%foo%" $today "3"}
```

## Invoke template

At the cursor caret position, select the template via `/` to trigger the template search, find the template that needs to be inserted and press Enter.

## An example

```cGxhaW50ZXh0
.action{$before := (div (now.Sub (toDate "2006-01-02" "2020-02-19")).Hours 24)}

.action{$after := (div ((toDate "2006-01-02" "2048-02-19").Sub now).Hours 24)}
Today is `.action{now | date "2006-01-02"}`.

* `.action{$before}` days have passed since `2020-02-19`
* There are `.action{$after}` days left from `2048-02-19`
```

`$before` and `$after` define two variables to record the number of days from the current date to 2020 and 2048, respectively.

## Push to template bazaar

Please make sure that the root path of your template repository contains at least the following files before listing ([repo example](https://github.com/88250/November-Rain)):

- template.json (please make sure the JSON format is correct)
- preview.png (please compress the image size within 512 KB)
- README.md (please note the case)

After confirmation, please [create a pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) to the [Community Bazaar](https://github.com/siyuan-note/bazaar) repository and modify the themes.json file in it. This file is the index file of all community template repositories, the format is:

```anNvbg==
{
   "repos": [
     "username/reponame@commithash"
   ]
}
```

Among them, `commithash`, please fill in the Git commit hash of the latest released version on your template repository, please use the full hash value instead of the 7-digit short value.

### Update

If the template you developed has an updated version, please remember:

- Update the version field in your template.json
- Create a Pull Request to the community bazaar

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20201227201128-m1wrouw.sy -->

# Docker hosting

## Overview

The easiest way to serve SiYuan on a server is to deploy it through Docker.

- Image name `b3log/siyuan`
- [Image URL](https://hub.docker.com/r/b3log/siyuan)

## File structure

The overall program is located under `/opt/siyuan/`, which is basically the structure under the resources folder of the Electron installation package:

- appearance: icon, theme, languages
- guide: user guide document
- stage: interface and static resources
- kernel: kernel program

## Entrypoint

The entry point is set when building the Docker image: `ENTRYPOINT ["/opt/siyuan/kernel" ]`, use `docker run b3log/siyuan` with parameters to start:

- `--workspace` specifies the workspace folder path, mounted to the container via `-v` on the host

More parameters can refer to here. The following is an example of a startup command: `docker run -v workspace_dir_host:workspace_dir_container -p 6806:6806 b3log/siyuan --workspace=workspace_dir_container`

- `workspace_dir_host`: the workspace folder path on the host
- `workspace_dir_container`: The path of the workspace folder in the container, which is the same as specified in `--workspace`

To simplify, it is recommended to configure the workspace folder path to be consistent on the host and container, such as: `workspace_dir_host` and `workspace_dir_container` are configured as `/siyuan/workspace`, the corresponding startup commands is: `docker run -v /siyuan/workspace:/siyuan/workspace -p 6806:6806 -u 1000:1000 b3log/siyuan --workspace=/siyuan/workspace/`.

## User permissions

In the image, the normal user `siyuan` (uid 1000/gid 1000) created by default is used to start the kernel process. Therefore, when the host creates a workspace folder, please pay attention to setting the user group of the folder:  `chown -R 1000:1000 /siyuan/workspace`. The parameter `-u 1000:1000` is required when starting the container.

## Hidden port

Use NGINX reverse proxy to hide port 6806, please note:

- Configure WebSocket reverse proxy `/ws`

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20201227201751-gv0fpx2.sy -->

# Kernel API

Please refer to [API Doc](https://github.com/siyuan-note/siyuan/blob/master/API.md).

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20210110181011-fbhoesf.sy -->

# Daily notes

We can quickly create a document through the daily note. The entry of the daily note function in the top toolbar looks like a calendar button.

But before using the daily note, you need to select settings in the right-click drop-down menu of the notebook, and configure in the new diary settings:

- Storage path: the path under the notebook, support template variables
- Template path (optional): use this template as the initial content when creating the daily note

Tips: Use in the specified template Embed Content Block to summarize to-do items or content blocks that need to be viewed daily.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20210127203829-qe2mzof.sy -->

# PDF annotation

## Insert PDF asset

After the PDF file is uploaded and inserted through the editor, the PDF will be placed in the assets folder, and a link in the form of `[filename](assets/filename.pdf)` will be generated in the document. Click the link to use SiYuan for preview.

## Hyperlink page jump

Open the new tab to preview the PDF and support the specified page number. You need to add the parameter `page` to the link. For example, if you need to jump to the seventh page, edit the link to `[filename](assets/filename.pdf?page=7)` .

## Annotation

The PDF preview can be marked by selection, and the annotation can be copied to the document:

- Click the reference link in the document to open the PDF and jump to the annotation
- Hover the mark in the PDF to preview the ref block

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20210331201142-4g923es.sy -->

# Hyperlink

## Overview

If you need to pull up the SiYuan desktop application in other places (such as a browser or software that supports hyperlinks), you can use the `siyuan://` hyperlink.

## Link format

`siyuan://blocks/{id}`: Open the content block directly, and the notebook where the block is located is already open.

Add query string parameter `focus=1` (`siyuan://blocks/{id}?focus=1`) to indicate focus is on.

## How to use

- After startup on Windows and macOS, it will automatically apply to the system for registration of the `siyuan://` protocol
- On Linux try the following steps
  - Create or find the `siyuan.desktop` file and open it for editing
    - `MimeType=MimeType=x-scheme-handler/siyuan;`
    - Add `%u` at the end of `Exec`, that is, `Exec=executable file path %u`
  - Execute the following commands
    ```amF2YQ==
sudo update-desktop-database
xdg-mime default siyuan.desktop x-scheme-handler/siyuan
xdg-settings set default-url-scheme-handler siyuan siyuan.desktop
```
    For more details, refer to [xdg-utils](https://www.freedesktop.org/wiki/Software/xdg-utils/).
- Block icon menu - Copy - Copy block hyperlink

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20210505164949-c085p1d.sy -->

# Web Clipping

## Overview

"Web Clipping" refers to copying the content on the Web page to SiYuan, and keeping its original format as much as possible.

## How to use

- If you do not need to pull the pictures contained in the clipped content to the local, you can directly select copy in the browser, and then paste it in SiYuan
- If you need to pull the pictures contained in the clipped content to the local, you can use [SiYuan Chome Extension](https://ld246.com/article/1629423901669)

### SiYuan Chrome Extension

1. Install the extension, configure the API token in the extended options (token can be viewed in SiYuan Settings - About)
2. Select the content to be clipped on the web page, and then select "Copy to SiYuan" from the right-click menu
3. Paste in SiYuan

If you need to clip the entire article, you can click "Send to SiYuan" directly on the extension.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20210615213222-vs5tzbd.sy -->

# Data history

## Overview

Data history is mainly used to ensure data security, and even if a misoperation occurs, data can be rolled back through the history. Historical data is uniformly stored in the `workspace/history/` folder. History will be automatically generated in the following cases:

- Every 10 minutes, a history will be generated for the documents updated within these 10 minutes. The interval can be set by <kbd>Settings</kbd> - <kbd>Editor</kbd> - <kbd>History Generation Interval</kbd> make adjustments, and the suffix of the history folder is `-update`
- When synchronizing in the cloud, the local data covered by the cloud will generate a history, and the suffix of the history folder is `-sync`
- History will be generated when manually deleting notebooks, documents and assets, and the suffix of the history folder is `-delete`
- When using Cleanup unreferenced assets, a history will be generated, and the suffix of the history folder is `-delete`
- When using the `Insert a space between Chinese and Western` function, a history will be generated, and the suffix of the history folder is `-format`

## Browsing History

- At the top <kbd>...</kbd> menu or <kbd>Alt+H</kbd> to open the history, only supports browsing the latest 32 times of history
- Browse under the filesystem `workspace/history/` folder

## Rollback

In the time list column on the left side of the history interface, there is a rollback button behind each historical record. After clicking, a confirmation dialog box will pop up. If the rollback is confirmed, the existing data will be overwritten with the historical data.

If there are very many files that need to be rolled back, it is recommended to manually copy on the file system. The internal structure of the history folder is the same as the internal structure of data, for example:

- Notebook delete: `2022-05-01-091021-delete/20210808180117-czj9bvb/`, i.e. `historical generation date-{operation}/{notebook ID}/`
- Document deletion: `2022-05-01-091209-delete/20210808180117-czj9bvb/20200812220555-lj3enxa.sy`, which is `historical generation date-{operation}/{notebook ID}/{document path}`
- Asset file deletion: `2022-05-01-095621-delete/assets/image-20220501091157-qccp87e.png`, which is `historical generation date-{operation}/assets/{asset file name}`

Manual rollback steps:

1. Exit SiYuan, and then make a full copy and backup of the entire workspace to avoid data loss caused by subsequent misoperations
2. Go to the `workspace/history/` folder and copy the data in the `historical generation date-{operation}` folder directly to the data folder for overwriting
3. Restart SiYuan

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20210824202056-udkf7wg.sy -->

# Widgets

## Overview

The widget is a static webpage served by SiYuan Kernel. It accesses data through API and renders it through `<iframe>`.

## How to use

The widgets are installed through the widget bazaar. After installation, the widgets will be placed in the workspace/widgets folder. In the editor, use the slash menu to trigger the call search. After selecting the widget you need, the widget will be inserted into the document in the form of a widget block.

## Push to widget bazaar

Please make sure that the root path of your icon repository contains at least the following files before listing:

- icon.json (please make sure the JSON format is correct)
- index.html
- preview.png (please compress the image size within 512 KB)
- README.md (please note the case)

After confirmation, please [create a pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) to the [Community Bazaar](https://github.com/siyuan-note/bazaar) repository and modify the consi.json file in it. This file is the index of all community icon repositories, the format is:

```anNvbg==
{
   "repos": [
     "username/reponame@commithash"
   ]
}
```

Among them, `commithash`, please fill in the Git commit hash of the latest released version on your icon repository, please use the full hash value instead of the 7-digit short value.

### Update

If the widget you developed has an updated version, please remember:

- Update the version field in your widget.json
- Create a Pull Request to the community bazaar

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o/20211010212318-3wx2kqb.sy -->

# Virtual reference

## Overview

Virtual reference is a kind of "block ref" that is automatically detected based on the anchor text of the existing block ref or the name of the block, but it is not actually linked to the block, but only marked in the editor, and supports floating window preview .

## How to use

Open the <kbd>Settings</kbd> - <kbd>Editor</kbd> - <kbd>Virtual Reference</kbd> switch.

## Detection rules

Search based on the anchor text/definition block text of the existing block ref, the name and alias of the block as keywords. If these keywords are searched on the plain text element of the current content block, it will be used as a virtual reference.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p/20210808180303-xaduj2o.sy -->

# General Operations

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234011-ieuun1p.sy -->

# Please Start Here

## 🍫 Content block

In SiYuan, the only important core concept is Content block. The content block can be formed through the formatting format, so that we can organize our thoughts and knowledge at the block-level granularity, and it is also convenient for reading and outputting long content.

## 🍔 Start eating

- Create a new notebook, create a new document under the notebook
- Enter <kbd>/</kbd> in the editor to trigger the function menu
- Navigate in the content block and Window and tab

## 🍹 Drink recommend

- FAQ
- [Origin](https://ld246.com/article/1619868273581)
- [Roadmap](https://github.com/siyuan-note/siyuan/projects)

## 🏘️ Our home

- [GitHub Issues](https://github.com/siyuan-note/siyuan/issues)
- [Discord](https://discord.gg/bzfCBwMzdP)

## 💌 Contribution

- Push to theme bazaar
- Push to template bazaar
- Push to icon bazaar
- Push to widget bazaar

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234602-gy54e67.sy -->

# Privacy Policy and User Agreement

## Privacy Policy

SiYuan's privacy policy document to declare its commitment to user privacy protection. Last updated February 9, 2022.

### Will personal information or data be collected?

- Does not collect user personal information and usage data (notes, asset files, operation records and program logs, etc.)
- All data is kept on the device under full control of the user

### Developer Information and Contact

- SiYuan is designed and developed by Yunnan Liandi Technology Co., Ltd.
- Contact via 845765@qq.com

### View Privacy Policy

- By visiting the webpage [https://b3log.org/siyuan/en/privacy.html](https://b3log.org/siyuan/en/privacy.html)
- Click "Help" in the software, and open the "Privacy Policy and License" document in the opened "SiYuan User Guide"

## User Agreement

This agreement applies and only applies to SiYuan (hereinafter referred to as "the software"), and Yunnan Liandi Technology Co., Ltd. has the final right to interpret this agreement.

Once you confirm this agreement and start to use the software, you are deemed to fully understand and accept the terms of this agreement. An agreement in the form of electronic text has full and equivalent legal effect as an agreement signed by both parties in writing.

While enjoying the power conferred by the terms, it is subject to relevant constraints and restrictions. Behaviors outside the scope of the agreement will directly violate this agreement and constitute infringement. We have the right to terminate the authorization at any time, order to stop the damage, and reserve the right to pursue relevant responsibilities.

### Licensed Rights

1. You can use the software within the constraints and limitations stipulated in the agreement
2. You own the ownership of the content written by using this software, and independently assume the relevant legal obligations related to these content

### Constraints and Restrictions under the Agreement

1. Development of derivative, modified or third-party versions of the software in whole or in part for redistribution without official permission is prohibited
2. It is forbidden to share the user account to use the software
3. If you fail to comply with the terms of this agreement, your authorization will be terminated, the licensed rights will be withdrawn, and you will assume the corresponding legal responsibility

### LIMITED WARRANTY AND DISCLAIMER

THIS SOFTWARE AND THE ACCOMPANYING DOCUMENTS ARE PROVIDED WITHOUT ANY EXPRESS OR IMPLIED INDEMNITY OR WARRANTY.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20200923234731-h3zkwm2.sy -->

# Frequently Asked Questions

## How does SiYuan store data?

The data is saved in the workspace folder (the default is in the user's home directory Documents/SiYuan, which can be modified in <kbd>Settings</kbd> - <kbd>About</kbd>), in the workspace data folder:

- `assets` are used to save all inserted assets
- `templates` are used to save template snippets
- `widgets` are used to save widgets
- `emojis` are used to save emoji images
- The rest of the folders are the notebook folders created by the user, files with the suffix of `.sy` in the notebook folder are used to save the document data, and the data format is JSON

## Is SiYuan open source?

SiYuan is completely open source, and contributions are welcome:

- [User Interface and Kernel](https://github.com/siyuan-note/siyuan)
- [User Guide](https://github.com/siyuan-note/user-guide-en_US)
- [Appearance](https://github.com/siyuan-note/appearance)
- [Data Parser](https://github.com/88250/protyle)
- [Editor Engine](https://github.com/88250/lute)
- [End-to-end encryption](https://github.com/siyuan-note/encryption)
- [Chrome Clipping Extension](https://github.com/siyuan-note/siyuan-chrome)
- [Android](https://github.com/siyuan-note/siyuan-android)
- [iOS](https://github.com/siyuan-note/siyuan-ios)

For more details, please refer to [Development Guide](https://github.com/siyuan-note/siyuan/blob/master/DEV.md).

## Is there any Note for deleting docs?

After deletion, the doc will not appear in the operating system's recycle bin, but will be deleted directly. When deleted, SiYuan will generate data history.

## How can I just wrap and not start a new paragraph?

Please use <kbd>Shift+Enter</kbd>.

## How to move the heading and blocks below it?

Fold the heading and move it later. Please note that it is a move, not a cut, and a folded heading cut will not move the blocks below it.

## How to select multiple blocks across pages?

Click at the beginning, hold down <kbd>Shift</kbd> and click at the end after scrolling the page.

## How to adjust table rows and columns?

There is an operation entry in the block icon menu of the table block.

## What if some blocks (such as paragraph blocks in list items) cannot find the block icon?

The first sub-block under the list item is the block icon omitted. You can move the cursor into this block and trigger its block menu with <kbd>Ctrl+/</kbd> .

## How to search for content containing symbols?

If you need to search for content containing symbols (`-`, `*`, etc.), you need to use `"` to wrap keywords, such as `"-siyuan"`. For details, please refer to Query syntax.

## How to use a third-party sync disk for data synchronization?

- Please only synchronize the `workspace/data/`, do not synchronize the entire workspace
- Please suspend third-party synchronization during the operation of SiYuan, otherwise data may be damaged. For details, please refer to [here](https://ld246.com/article/1626537583158)
- The data folder path on the Android is `internal storage device/Android/data/org.b3log.siyuan/files/siyuan/data/`, which is a private path of the application and cannot be read by other programs and can only be copied manually
- There is a conflict between third-party synchronization and SiYuan synchronization, please do not use at the same time

## What should I do if I forget the end-to-end password?

1. Use the new workspace on the main device, manually copy the old workspace data folder to the new workspace
2. New workspace can reset password
3. The cloud uses the new cloud synchronization directory

If it is a mobile-end, uninstall and reinstall it (Note: When the mobile-enduninstalls the application, the local workspace data will be deleted together).

## Do I need to pay for it?

Local functions are completely free to use, [Cloud services](https://b3log.org/siyuan/pricing.html) requires annual subscription, price is $72/year。

Users in non-Mainland China regions should not pay for subscriptions, because SiYuan Cloud Server cannot guarantee availability in non-Mainland China regions.

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20201121224345-rc27qvo.sy -->

# Acknowledgements

SiYuan is made possible by the following open source projects.

- [https://github.com/golang/go](https://github.com/golang/go) `BSD-3-Clause License`
- [https://github.com/atotto/clipboard](https://github.com/atotto/clipboard) `BSD-3-Clause License`
- [https://github.com/vanng822/css](https://github.com/vanng822/css) `MIT License`
- [https://github.com/gofrs/flock](https://github.com/gofrs/flock) `BSD-3-Clause License`
- [https://github.com/88250/gulu](https://github.com/88250/gulu) `Mulan PSL v2`
- [https://github.com/88250/lute](https://github.com/88250/lute) `Mulan PSL v2`
- [https://github.com/olahol/melody](https://github.com/olahol/melody) `BSD-2-Clause License`
- [https://github.com/pdfcpu/pdfcpu](https://github.com/pdfcpu/pdfcpu) `Apache-2.0 License`
- [https://github.com/88250/protyle](https://github.com/88250/protyle) `Mulan PSL v2`
- [https://github.com/blastrain/vitess-sqlparser](https://github.com/blastrain/vitess-sqlparser) `Apache-2.0 License`
- [https://github.com/ConradIrwin/font](https://github.com/ConradIrwin/font) `MIT License`
- [https://github.com/Masterminds/sprig](https://github.com/Masterminds/sprig) `MIT License`
- [https://github.com/PuerkitoBio/goquery](https://github.com/PuerkitoBio/goquery) `BSD-3-Clause License`
- [https://github.com/araddon/dateparse](https://github.com/araddon/dateparse) `MIT License`
- [https://github.com/common-nighthawk/go-figure](https://github.com/common-nighthawk/go-figure) `MIT License`
- [https://github.com/denisbrodbeck/machineid](https://github.com/denisbrodbeck/machineid) `MIT License`
- [https://github.com/dgraph-io/ristretto](https://github.com/dgraph-io/ristretto) `Apache-2.0 License`
- [https://github.com/dustin/go-humanize](https://github.com/dustin/go-humanize) `MIT License`
- [https://github.com/emirpasic/gods](https://github.com/emirpasic/gods) `BSD-2-Clause License`
- [https://github.com/facette/natsort](https://github.com/facette/natsort) `BSD-3-Clause License`
- [https://github.com/flopp/go-findfont](https://github.com/flopp/go-findfont) `MIT License`
- [https://github.com/fsnotify/fsnotify](https://github.com/fsnotify/fsnotify) `BSD-3-Clause License`
- [https://github.com/gin-contrib/cors](https://github.com/gin-contrib/cors) `MIT License`
- [https://github.com/gin-contrib/gzip](https://github.com/gin-contrib/gzip) `MIT License`
- [https://github.com/gin-contrib/sessions](https://github.com/gin-contrib/sessions) `MIT License`
- [https://github.com/gin-gonic/gin](https://github.com/gin-gonic/gin) `MIT License`
- [https://github.com/imroc/req](https://github.com/imroc/req) `MIT License`
- [https://github.com/jinzhu/copier](https://github.com/jinzhu/copier) `MIT License`
- [https://github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) `MIT License`
- [https://github.com/mattn/go-zglob](https://github.com/mattn/go-zglob) `MIT License`
- [https://github.com/mitchellh/go-ps](https://github.com/mitchellh/go-ps) `MIT License`
- [https://github.com/mssola/user_agent](https://github.com/mssola/user_agent) `MIT License`
- [https://github.com/panjf2000/ants](https://github.com/panjf2000/ants) `MIT License`
- [https://github.com/patrickmn/go-cache](https://github.com/patrickmn/go-cache) `MIT License`
- [https://github.com/radovskyb/watcher](https://github.com/radovskyb/watcher) `BSD-3-Clause License`
- [https://github.com/siyuan-note/encryption](https://github.com/siyuan-note/encryption) `Mulan PSL v2`
- [https://github.com/vmihailenco/msgpack](https://github.com/vmihailenco/msgpack) `BSD-2-Clause License`
- [https://github.com/xrash/smetrics](https://github.com/xrash/smetrics) `MIT License`
- [https://github.com/microsoft/TypeScript](https://github.com/microsoft/TypeScript) `Apache-2.0 License`
- [https://github.com/electron/electron](https://github.com/electron/electron) `MIT License`
- [https://github.com/Vanessa219/vditor](https://github.com/Vanessa219/vditor) `MIT License`
- [https://github.com/visjs/vis-network](https://github.com/visjs/vis-network) `Apache-2.0 License`
- [https://github.com/mozilla/pdf.js](https://github.com/mozilla/pdf.js) `Apache-2.0 License`
- [https://github.com/blueimp/JavaScript-MD5](https://github.com/blueimp/JavaScript-MD5) `MIT License`

---

<!-- Source: https://github.com/siyuan-note/user-guide-en_US/blob/master/20210117215840-jcl17fx.sy -->

# Data Security

## Overview

Data security is mainly divided into two aspects:

- Availability: no data loss, no conflict, keep the data complete and consistent
- Confidentiality: data will not be leaked or tampered with

SiYuan supports both of these aspects. The following is an explanation about data security.

## Plaintext storage

SiYuan uses plaintext to store data on the local file system, which means:

- Anyone or software who can use the operating system can read the data in it
- The availability of data depends on the availability of hardware disks and operating systems

## End-to-end encryption

SiYuan cloud backup and synchronization use end-to-end encryption, the password is stored locally with a built-in key encryption, any third party other than the user cannot get the plaintext in the cloud data.

## Suggest

- Regularly back up data to the cloud and offline devices at the same time
- It is recommended to use special software, equipment or offline storage for important passwords, keys or core secrets