Skip to content

Commit

Permalink
docs: update README
Browse files Browse the repository at this point in the history
  • Loading branch information
observerw committed Jul 10, 2024
1 parent 535aa8e commit 3706f02
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 15 deletions.
20 changes: 13 additions & 7 deletions README-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<div align="center">

![GitHub stars](https://img.shields.io/github/stars/observerw/obsidian-code-link?style=flat) ![latest download](https://img.shields.io/github/downloads/observerw/obsidian-code-link/latest/total?style=plastic)
[![Github release](https://img.shields.io/github/manifest-json/v/observerw/obsidian-code-link?color=blue)](https://github.com/Benature/obsidian-text-format/releases/latest) ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/observerw/obsidian-code-link?include_prereleases&label=BRAT%20beta)
[![Github release](https://img.shields.io/github/manifest-json/v/observerw/obsidian-code-link?color=blue)](https://github.com/observerw/obsidian-code-link/releases/latest) ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/observerw/obsidian-code-link?include_prereleases&label=BRAT%20beta)

[ [English](./README.md) | [简体中文](./README-CN.md) ]

Expand All @@ -16,23 +16,23 @@
- **像链接笔记一样链接代码文件**,并且你可以**预览它们的内容**
- 通过符号搜索/标签搜索/代码大纲(或者你想叫它什么都可以), 你可以**直接链接到代码文件中的特定符号**(例如类、函数、或者类中的方法)。

通过使用符号创建链接,你可以在笔记中引用你感兴趣的代码部分,避免其他代码内容的干扰。这在学习复杂的开源项目时特别有用。
通过使用符号创建链接,你可以在笔记中引用你感兴趣的代码部分,避免其他内容的干扰。这在学习复杂的开源项目时特别有用。

# ⚠️注意

- 为了能够使用内部链接链接到代码文件,请确保**设置 - 文件和链接 - 检测所有类型的文件**选项已启用。
- **嵌入式预览仅在阅读视图中有效**,所以如果你发现预览没有显示,请按 `Ctrl/Cmd + E` 切换到阅读视图。
- 在执行标签搜索之前,请确保设置 - 代码链接 - **启用标签搜索选项**已启用,并且必要的组件已下载(通过**点击下载必要组件按钮**
- 在执行标签搜索之前,请确保设置 - 代码链接 - **启用标签搜索选项**已启用,并且**必要的组件已下载**(通过点击下载必要组件按钮

<div style="display: flex; justify-content: center;">
<img src="./assets/download-button.png" width="100%">
</div>

# 使用方法

1. 在 Obsidian 仓库中创建一个文件夹,用于存储代码项目的符号链接,路径默认为 `projects`
2. 打开命令面板,运行 `Code Link: Import project`,选择要导入的项目文件夹,然后项目将被导入到你在步骤 1 中创建的文件夹中。
3. 打开编辑器,像链接笔记一样链接到代码文件,然后你可以在编辑器中预览代码
1. 在 Obsidian 仓库中创建一个文件夹,用于存储导入的代码项目,路径默认为 `projects`
2. 打开命令面板,运行 `Code Link: Import project`,选择要导入的项目文件夹(详见[下面的介绍](#将项目导入-obsidian-仓库),然后项目将被导入到你在步骤 1 中创建的文件夹中。
3. 打开编辑器,像链接笔记一样链接到代码文件,然后就可以在编辑器中预览代码了

# 代码预览

Expand All @@ -46,7 +46,9 @@
<img src="./assets/embed.png" width="100%">
</div>

在嵌入式预览下方列出了对所引用的代码文件的链接,以及当前符号的标签路径(例如,如果你链接到一个名为 methodB 的方法,它在一个名为 ClassA 的类中,标签路径是 `class ClassA > def methodB`)。当你点击标签路径中的符号时,嵌入式预览将临时将显示的代码内容切换到该符号的内容。
在嵌入式预览下方列出了对所引用的代码文件的链接,以及当前符号的标签路径(例如,如果你链接到一个名为 `methodB` 的方法,它在一个名为 `ClassA` 的类中,标签路径是 `class ClassA > def methodB`)。当你点击标签路径中的符号时,嵌入式预览将临时将显示的代码内容切换到该符号的内容。



# 标签搜索

Expand All @@ -58,6 +60,10 @@

此功能是通过 [TreeSitter](https://tree-sitter.github.io/tree-sitter/)[zed 编辑器的 .scm 文件](https://zed.dev/) 实现的。

If you want more languages to be supported, please consider writing tree-sitter queries for other languages modeled after existing `.scm` files and open a pull request. I would appreciate it!

如果你希望支持更多的语言,请考虑模仿[现有的 `.scm` 文件](https://github.com/observerw/obsidian-code-link/tree/main/src/lang/data/scm)编写其他语言的 tree-sitter 查询,并提交一个Pull Request。感激不尽!

# 将项目导入 Obsidian 仓库

Obsidian 仅允许链接到仓库内的文件,所以你需要将项目导入到你的仓库中才能链接到它。
Expand Down
18 changes: 10 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,35 +3,35 @@
<div align="center">

![GitHub stars](https://img.shields.io/github/stars/observerw/obsidian-code-link?style=flat) ![latest download](https://img.shields.io/github/downloads/observerw/obsidian-code-link/latest/total?style=plastic)
[![Github release](https://img.shields.io/github/manifest-json/v/observerw/obsidian-code-link?color=blue)](https://github.com/Benature/obsidian-text-format/releases/latest) ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/observerw/obsidian-code-link?include_prereleases&label=BRAT%20beta)
[![Github release](https://img.shields.io/github/manifest-json/v/observerw/obsidian-code-link?color=blue)](https://github.com/observerw/obsidian-code-link/releases/latest) ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/observerw/obsidian-code-link?include_prereleases&label=BRAT%20beta)

[ [English](./README.md) | [简体中文](./README-CN.md) ]

</div>

Display code everywhere, and only the parts you're interested in!
Display code in Obsidian, and only the part you're interested in!

![main](./assets/main.png)

- **Link to code files** as you would link to notes, and you can **preview their contents**.
- Even better, through symbol search/tag search/code outline (or whatever you want to call it.), you can **link directly to a specific symbol in the code file** (such as a class, a function, or a method within a class).

By creating links with symbols, you can reference only the code parts that interest you in your notes and avoid distractions from other code content. This is particularly useful when taking code notes (for example, when studying a complex open-source project).
By creating links with symbols, you can reference only the code parts that interest you in your notes and avoid distractions from other content. This is particularly useful when taking code notes (for example, when studying a complex open-source project).

# ⚠️ATTENTION

- To be able to link to the code file with internal link, make sure that the **Settings - Files and Links - Detect all types of files** option are enabled.
- **Embed preview only works in reading view**, so if you find that the preview is not displayed, please **switch to reading view** by pressing `Ctrl/Cmd + E`.
- Before you perform a tag search, make sure that Settings - Code Link - **Enable tag search option** is enabled and necessary components have been downloaded (by **clicking the Download necessary components button**)
- Before you perform a tag search, make sure that Settings - Code Link - **Enable tag search option** is enabled and **necessary components have been downloaded** (by clicking the Download necessary components button).

<div style="display: flex; justify-content: center;">
<img src="./assets/download-button.png" width="100%">
</div>

# Usage

1. Create a folder in your obsidian repository for storing symlinks of your code projects, the default path is `projects`.
2. Open Command Palette and run `Code Link: Import project`, select the project folder you want to import, then the project will be imported into the folder you created in step 1.
1. Create a folder in your obsidian repository for storing imported projects of your code projects, the default path is `projects`.
2. Open Command Palette and run `Code Link: Import project`, select the project folder you want to import (see [this section](#import-project-into-obsidian-vault) below), then the project will be imported into the folder you created in step 1.
3. Open editor, link to the code file just like linking to a note, then you can preview the code in the editor.

# Code Preview
Expand All @@ -47,7 +47,7 @@ Supports both hover preview and embed preview of the code file.
</div>


Below the embed preview lists the link to the referenced code file, and the tag path to the current symbol (e.g., if you link to a method named methodB in a class named ClassA, the tag path is `class ClassA > def methodB`). When you click on a symbol in the tag path, the embed preview will temporarily switch the content of the displayed code to the content of that symbol.
Below the embed preview lists the link to the referenced code file, and the tag path to the current symbol (e.g., if you link to a method named `methodB` in a class named `ClassA`, the tag path is `class ClassA > def methodB`). When you click on a symbol in the tag path, the embed preview will temporarily switch the content of the displayed code to the content of that symbol.

# Tag Search

Expand All @@ -57,7 +57,9 @@ Below the embed preview lists the link to the referenced code file, and the tag
<img src="./assets/tag-search.png" width="50%">
</div>

This feature is implemented with the help of [TreeSitter](https://tree-sitter.github.io/tree-sitter/) and [.scm files from the zed editor](https://zed.dev/).
This feature is implemented with the help of [TreeSitter](https://tree-sitter.github.io/tree-sitter/) and [`.scm` files from the zed editor](https://zed.dev/).

If you want more languages to be supported, please consider writing tree-sitter queries for other languages modeled after [existing `.scm` files](https://github.com/observerw/obsidian-code-link/tree/main/src/lang/data/scm) and open a pull request. I would appreciate that!

# Import Project Into Obsidian Vault

Expand Down

0 comments on commit 3706f02

Please sign in to comment.