logseq-organization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Logseq Organization

Logseq 组织规范

This skill guides how to structure, format, and organize Logseq notes. The user has very specific conventions for directory structures, journals, namespaces (which act as folders), and block properties/tags within their Logseq vault.
此 skill 指导如何构建、格式化和组织 Logseq 笔记。用户对 Logseq vault 内的目录结构、Journal、namespace(其作用类似于文件夹)以及 block properties/tags 有非常明确的约定。

Vault Directory Structure

Vault 目录结构

A standard Logseq vault has specific directories for different types of notes. ALWAYS create or modify files in their respective directories:
  • Journals:
    journals/
    directory.
  • Pages:
    pages/
    directory.
标准的 Logseq vault 包含用于不同类型笔记的特定目录。始终应在各自的目录中创建或修改文件:
  • Journal:
    journals/
    目录。
  • Page:
    pages/
    目录。

Journal Organization (
journals/
directory)

Journal 组织(
journals/
目录)

All journal files MUST be placed in the
journals/
directory. The filename format is exactly
YYYY_MM_DD.md
(e.g.,
journals/2026_05_30.md
).
Within these files, the user categorizes their entries using second-level headings combined with hashtags as Logseq page links. ALWAYS use the following format for these categories. They must be second-level headings (preceded by
- ## 
) so they nest properly in the Logseq outliner:
  • - ## #learnings
  • - ## #achievements
  • - ## #highlights
  • - ## #links
    • External links must ALWAYS be written in standard Markdown format:
      [Link Text](https://url...)
      .
Example Journal Entry (
journals/2026_05_30.md
):
markdown
- ## #learnings
	- Learned about how VerticalPodAutoscaler works in Kubernetes. #kubernetes
- ## #links
	- [How I write HTTP services in Go](https://grafana.com/...)
所有 Journal 文件都必须放在
journals/
目录中。 文件名格式必须严格使用
YYYY_MM_DD.md
(例如
journals/2026_05_30.md
)。
在这些文件中,用户使用二级标题与 hashtag 组合来分类条目,并将其作为 Logseq page 链接。分类始终必须使用以下格式。它们必须是二级标题(前缀为
- ## 
),以便在 Logseq outliner 中正确嵌套:
  • - ## #learnings
  • - ## #achievements
  • - ## #highlights
  • - ## #links
    • 外部链接必须始终使用标准 Markdown 格式:
      [Link Text](https://url...)
      。
Journal 条目示例(
journals/2026_05_30.md
):
markdown
- ## #learnings
	- Learned about how VerticalPodAutoscaler works in Kubernetes. #kubernetes
- ## #links
	- [How I write HTTP services in Go](https://grafana.com/...)

Content Guidelines

内容指南

  • When writing entries under categories like
    #learnings
    or
    #achievements
    , always focus on meaningful text first for the top line. Do not start the line with tags; place any high-level tags at the end of the line or in nested blocks.
  • 在
    #learnings
    或
    #achievements
    等分类下写入条目时,首行应始终优先呈现有意义的内容。不要以 tags 开头;应将高层级 tags 放在该行末尾或嵌套 block 中。

Referencing Journals

引用 Journal

When linking to or referencing a Journal entry from another page or block, ALWAYS use the format
[[D MMM YYYY]]
or
[[DD MMM YYYY]]
(e.g.,
[[1 Jun 2026]]
,
[[15 Aug 2025]]
). Do not use the file name format (
YYYY_MM_DD
) for inline references.
从另一个 page 或 block 链接或引用 Journal 条目时,始终使用
[[D MMM YYYY]]
或
[[DD MMM YYYY]]
格式(例如
[[1 Jun 2026]]
、
[[15 Aug 2025]]
)。内联引用中不得使用文件名格式(
YYYY_MM_DD
)。

Note Organization (
pages/
directory)

Note 组织(
pages/
目录)

All non-journal notes MUST be placed in the
pages/
directory.
The user organizes these notes into pseudo-folders using Logseq's namespace feature. This is represented by a triple-underscore
___
in the filename on disk.
When creating files for categorized pages, ALWAYS use the
pages/<namespace>___<page-name>.md
filename format. Common namespaces include:
  • Projects:
    projects___<type>___<project-name>
    (see Project Types below)
  • Content:
    podcasts___Highlights
    ,
    articles___Highlights
    ,
    books___Highlights
  • Meetings:
    Meetings___1-1___<Person>
    ,
    Meetings___Agenda
  • Other areas:
    learnings___<topic>
    ,
    Upkeep___<topic>
    ,
    Work___<person>
所有非 Journal 笔记都必须放在
pages/
目录中。
用户使用 Logseq 的 namespace 功能,将这些笔记组织到伪文件夹中。在磁盘上的文件名中,这通过三个下划线
___
表示。
创建分类 Page 的文件时,始终使用
pages/<namespace>___<page-name>.md
文件名格式。常见 namespace 包括:
  • 项目:
    projects___<type>___<project-name>
    (参见下方的项目类型)
  • 内容:
    podcasts___Highlights
    、
    articles___Highlights
    、
    books___Highlights
  • 会议:
    Meetings___1-1___<Person>
    、
    Meetings___Agenda
  • 其他领域:
    learnings___<topic>
    、
    Upkeep___<topic>
    、
    Work___<person>

Project Types

项目类型

Projects live under the
projects
namespace and are further organized by type. Known project types:
TypeDescriptionExample filename
work
Projects at work
pages/projects___work___platform migration.md
personal
Hobby projects and experiments
pages/projects___personal___learning nix.md
khidmat
Volunteer projects for the user's community
pages/projects___khidmat___event website.md
[!IMPORTANT] When creating a new project page and the project type is not obvious from context, you MUST ask the user which type it is before creating the file. Do not guess. The user may also specify a type not listed above — use whatever they provide.
Example File Paths:
  • pages/projects___personal___learning nix.md
  • pages/projects___work___ci pipeline revamp.md
  • pages/projects___khidmat___event website.md
  • pages/podcasts___Highlights___Supercharging Developer Productivity.md
  • pages/Meetings___1-1___Abhay.md
项目位于
projects
namespace 下,并进一步按类型组织。已知项目类型如下:
类型说明文件名示例
work
工作项目
pages/projects___work___platform migration.md
personal
个人业余项目和实验
pages/projects___personal___learning nix.md
khidmat
用户所在社区的志愿项目
pages/projects___khidmat___event website.md
[!IMPORTANT] 创建新的项目 Page 时,如果无法根据上下文明确判断项目类型,必须先询问用户,不得自行猜测。用户也可能指定列表中未包含的类型——此时使用用户提供的类型。
文件路径示例:
  • pages/projects___personal___learning nix.md
  • pages/projects___work___ci pipeline revamp.md
  • pages/projects___khidmat___event website.md
  • pages/podcasts___Highlights___Supercharging Developer Productivity.md
  • pages/Meetings___1-1___Abhay.md

Referencing Pages

引用 Page

When linking to or referencing a namespaced page from another page or block, ALWAYS use
/
(forward slash) as the namespace separator inside wikilinks — NOT
___
. The
___
convention is ONLY for filenames on disk. Logseq automatically maps
[[namespace/page]]
to the corresponding
namespace___page.md
file.
Examples (filename → inline reference):
  • pages/learnings___kubernetes.md
    →
    [[learnings/kubernetes]]
  • pages/projects___personal___learning nix.md
    →
    [[projects/personal/learning nix]]
  • pages/Meetings___1-1___Abhay.md
    →
    [[Meetings/1-1/Abhay]]
从另一个 page 或 block 链接或引用带 namespace 的 Page 时,wikilink 内部始终使用
/
(正斜杠)作为 namespace 分隔符,不得使用
___
。
___
约定仅用于磁盘上的文件名。Logseq 会自动将
[[namespace/page]]
映射到对应的
namespace___page.md
文件。
示例(文件名 → 内联引用):
  • pages/learnings___kubernetes.md
    →
    [[learnings/kubernetes]]
  • pages/projects___personal___learning nix.md
    →
    [[projects/personal/learning nix]]
  • pages/Meetings___1-1___Abhay.md
    →
    [[Meetings/1-1/Abhay]]

Organizational Priority

组织优先级

To prevent duplicate root-level pages and maintain a clean vault:
  • Namespaces > Hashtags: If a namespaced page exists (e.g.,
    [[learnings/VAPID]]
    ), ALWAYS use that link instead of a generic hashtag (e.g.,
    #VAPID
    ).
  • Avoid Root Tags for Namespaces: Generic and high-level tags are perfectly fine. However, never use hashtags for topics that have a dedicated home in a namespace.
  • Link Format: Use the wikilink format
    [[namespace/page]]
    in the daily journal to correctly reference the corresponding
    pages/namespace___page.md
    file.
为防止产生重复的根级 Page 并保持 vault 整洁:
  • namespace > hashtag:如果存在带 namespace 的 Page(例如
    [[learnings/VAPID]]
    ),始终使用该链接,而不是通用 hashtag(例如
    #VAPID
    )。
  • 避免为 namespace 使用根级 tags:通用和高层级 tags 完全可以使用且受到鼓励。但是,对于已经组织到 namespace 中的主题,不得使用 hashtags。
  • 链接格式:在 Journal 中使用 wikilink 格式
    [[namespace/page]]
    ,以正确引用对应的
    pages/namespace___page.md
    文件。

Tags and Properties

Tags 与 Properties

Pages and blocks are categorized using Logseq properties, primarily
tags::
and
category::
.
[!NOTE] Generic and high-level tags are fine and encouraged. However, do not use
#tagname
for topics that are already organized into namespaces. Liberal use of hashtags for namespaced topics creates duplicate pages at the root of the vault.
  1. Format:
    • If a tag is a single word (no spaces), prefix it with
      #
      :
      #tagname
    • If a tag contains a space, use the wikilinks format:
      [[tag name]]
      or
      #[[tag name]]
  2. Placement: Property blocks are typically the first block on a page.
  3. Common Tags:
    • #favorite
    • #productivity
    • #management
      ,
      #leadership
    • #devops
      ,
      #engineering
      ,
      [[platform engineering]]
    • [[machine learning]]
      ,
      [[AI for coding]]
  4. Categories: Use
    category:: #podcasts
    or
    category:: #articles
    on highlight pages.
Example Page Header:
markdown
tags:: #favorite, #management, #productivity, [[platform engineering]]
category:: #articles

- Here are the notes for this article...
Whenever you are asked to create a new Logseq note, add an entry to a journal, or organize information, strictly adhere to these vault directory and formatting conventions.
Page 和 block 使用 Logseq properties 进行分类,主要包括
tags::
和
category::
。
[!NOTE] 通用和高层级 tags 可以使用,并且建议积极使用。但是,对于已经组织到 namespace 中的主题,不得使用
#tagname
。大量将带 namespace 的主题用作 hashtag 会在 vault 根目录中产生重复 Page。
  1. 格式:
    • 如果 tag 是单个单词(不含空格),使用
      #
      作为前缀:
      #tagname
    • 如果 tag 包含空格,使用 wikilinks 格式:
      [[tag name]]
      或
      #[[tag name]]
  2. 位置:Property blocks 通常位于 Page 的第一个 block。
  3. 常用 Tags:
    • #favorite
    • #productivity
    • #management
      、
      #leadership
    • #devops
      、
      #engineering
      、
      [[platform engineering]]
    • [[machine learning]]
      、
      [[AI for coding]]
  4. 分类:在 highlights Page 上使用
    category:: #podcasts
    或
    category:: #articles
    。
Page 头部示例:
markdown
tags:: #favorite, #management, #productivity, [[platform engineering]]
category:: #articles

- Here are the notes for this article...
每当需要创建新的 Logseq note、向 Journal 添加条目或组织信息时,都必须严格遵守上述 vault 目录与格式约定。