📝 doc: add developer guide document

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);
+}
+```

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);
+}
+```