From 4a7bd848a960a66bd549012de7a659fa5a30dea5 Mon Sep 17 00:00:00 2001
From: frostime <frostime@foxmail.com>
Date: Sat, 16 Mar 2024 13:43:27 +0800
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20doc:=20add=20developer=20guide?=
=?UTF-8?q?=20document?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++
README_zh_CN.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 107 insertions(+)
diff --git a/README.md b/README.md
index df5278b..981ca43 100644
--- a/README.md
+++ b/README.md
@@ -233,3 +233,56 @@ If you insist on removing all svelte dependencies so that they do not pollute yo
- Line 20: `svelte(),`
4. delete line 37 of `tsconfig.json` from `"svelte"` 5.
5. re-run `pnpm i`
+
+## Developer's Guide
+
+Developers of SiYuan need to pay attention to the following specifications.
+
+### 1. File Reading and Writing Specifications
+
+If plugins or external extensions require direct reading or writing of files under the `data` directory, please use the kernel API to achieve this. **Do not call `fs` or other electron or nodejs APIs directly**, as it may result in data loss during synchronization and cause damage to cloud data.
+
+Related APIs can be found at: `/api/file/*` (e.g., `/api/file/getFile`).
+
+### 2. Daily Note Attribute Specifications
+
+When creating a diary in SiYuan, a custom-dailynote-yyyymmdd attribute will be automatically added to the document to distinguish it from regular documents.
+
+> For more details, please refer to [Github Issue #9807](https://github.com/siyuan-note/siyuan/issues/9807).
+
+Developers should pay attention to the following when developing the functionality to manually create Daily Notes:
+
+- If `/api/filetree/createDailyNote` is called to create a diary, the attribute will be automatically added to the document, and developers do not need to handle it separately.
+- If a document is created manually by developer's code (e.g., using the `createDocWithMd` API to create a diary), please manually add this attribute to the document.
+
+Here is a reference code:
+
+```ts
+/*
+ * Copyright (c) 2023 by frostime. All Rights Reserved.
+ * @Author : frostime
+ * @Url : https://github.com/frostime/siyuan-dailynote-today/blob/v1.3.0/src/func/dailynote/dn-attr.ts
+ */
+
+export function formatDate(date?: Date, sep=''): string {
+ date = date === undefined ? new Date() : date;
+ let year = date.getFullYear();
+ let month = date.getMonth() + 1;
+ let day = date.getDate();
+ return `${year}${sep}${month < 10 ? '0' + month : month}${sep}${day < 10 ? '0' + day : day}`;
+}
+
+/**
+ * Set custom attribute: `custom-dailynote-yyyyMMdd`: yyyyMMdd
+ * https://github.com/siyuan-note/siyuan/issues/9807
+ * @param doc_id Id of daily note
+ */
+export function setCustomDNAttr(doc_id: string, date?: Date) {
+ let td = formatDate(date);
+ let attr = `custom-dailynote-${td}`;
+ // 构建 attr: td
+ let attrs: { [key: string]: string } = {};
+ attrs[attr] = td;
+ serverApi.setBlockAttrs(doc_id, attrs);
+}
+```
diff --git a/README_zh_CN.md b/README_zh_CN.md
index c24a95e..b2d3ad3 100644
--- a/README_zh_CN.md
+++ b/README_zh_CN.md
@@ -224,3 +224,57 @@ PR 社区集市仓库。
- 第二十行: `svelte(),`
4. 删掉 `tsconfig.json` 中 37 行 `"svelte"`
5. 重新执行 `pnpm i`
+
+
+## 开发者须知
+
+思源开发者需注意以下规范。
+
+### 1. 读写文件规范
+
+插件或者外部扩展如果有直接读取或者写入 data 下文件的需求，请通过调用内核 API 来实现，**不要自行调用 `fs` 或者其他 electron、nodejs API**，否则可能会导致数据同步时分块丢失，造成云端数据损坏。
+
+相关 API 见: `/api/file/*`（例如 `/api/file/getFile` 等）。
+
+### 2. Daily Note 属性规范
+
+思源在创建日记的时候会自动为文档添加 custom-dailynote-yyyymmdd 属性, 以方便将日记文档同普通文档区分。
+
+> 详情请见 [Github Issue #9807](https://github.com/siyuan-note/siyuan/issues/9807)。
+
+开发者在开发手动创建 Daily Note 的功能时请注意：
+
+- 如果调用了 `/api/filetree/createDailyNote` 创建日记，那么文档会自动添加这个属性，无需开发者特别处理。
+- 如果是开发者代码手动创建文档（例如使用 `createDocWithMd` API 创建日记），请手动为文档添加该属性。
+
+参考代码:
+
+```ts
+/*
+ * Copyright (c) 2023 by frostime. All Rights Reserved.
+ * @Author : frostime
+ * @Url : https://github.com/frostime/siyuan-dailynote-today/blob/v1.3.0/src/func/dailynote/dn-attr.ts
+ */
+
+export function formatDate(date?: Date, sep=''): string {
+ date = date === undefined ? new Date() : date;
+ let year = date.getFullYear();
+ let month = date.getMonth() + 1;
+ let day = date.getDate();
+ return `${year}${sep}${month < 10 ? '0' + month : month}${sep}${day < 10 ? '0' + day : day}`;
+}
+
+/**
+ * Set custom attribute: `custom-dailynote-yyyyMMdd`: yyyyMMdd
+ * https://github.com/siyuan-note/siyuan/issues/9807
+ * @param doc_id Id of daily note
+ */
+export function setCustomDNAttr(doc_id: string, date?: Date) {
+ let td = formatDate(date);
+ let attr = `custom-dailynote-${td}`;
+ // 构建 attr: td
+ let attrs: { [key: string]: string } = {};
+ attrs[attr] = td;
+ serverApi.setBlockAttrs(doc_id, attrs);
+}
+```