{"id":23436895,"url":"https://github.com/logseq/handbooks","last_synced_at":"2025-07-14T16:04:57.919Z","repository":{"id":205315359,"uuid":"585872991","full_name":"logseq/handbooks","owner":"logseq","description":"Handbooks resources for Logseq.","archived":false,"fork":false,"pushed_at":"2025-01-21T19:09:19.000Z","size":129783,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-03T07:34:59.077Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/logseq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-06T10:06:00.000Z","updated_at":"2025-05-10T13:51:37.000Z","dependencies_parsed_at":"2025-04-13T04:52:04.344Z","dependency_job_id":null,"html_url":"https://github.com/logseq/handbooks","commit_stats":{"total_commits":115,"total_committers":7,"mean_commits":"16.428571428571427","dds":0.5739130434782609,"last_synced_commit":"a5e9b3b60fc1a7ef643a11e4ac4fd722e856ed96"},"previous_names":["logseq/handbooks"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/logseq/handbooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logseq%2Fhandbooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logseq%2Fhandbooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logseq%2Fhandbooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logseq%2Fhandbooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/logseq","download_url":"https://codeload.github.com/logseq/handbooks/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logseq%2Fhandbooks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264940397,"owners_count":23686250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-23T13:34:45.645Z","updated_at":"2025-07-14T16:04:57.833Z","avatar_url":"https://github.com/logseq.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📖 Handbook specifications\n\nThe current handbook resources are all stored in the `docs` directory.\n\n## Root\n\nIn the handbook root directory (`./docs`), there is a global configuration file `docs/config.edn` that describes the basic meta information\nof handbook.\n\n```clojure\n{:title          \"Logseq Handbook\"\n :version        \"0.0.1\"\n\n ;; [optional] Currently, the children items will be built from categories folders\n ;; :children []\n\n ;; [optional] popular topics from home\n :popular-topics [\"1.Onboarding/1.welcome-to-logseq\"]\n\n ;; more options will be supported ...\n }\n```\n\n\u003e ❓As for why `edn` is used as the configuration file format instead of `json`,\n\u003e it is mainly because `edn` supports richer data types, as well as comments,\n\u003e which are beneficial for future scalability, and writing experience.\n\u003e https://github.com/edn-format/edn\n\n## Categories\n\nThe current top-level grouping of Handbook is abstracted through `Category`,\nwhich are derived from the first level of directories under `docs/*`.\nEach Category folder also corresponds to a configuration file `docs/your-category-name/config.edn`,\nwhich is used to configure the meta information of the `category`.\n\n```clojure\n{:title       \"🔆 Onboarding\"\n :description \"This is sub description\"\n :color       \"#dd2624\"\n\n ;; [optional] children as topics, if not set this field,\n ;; the children will be built from all topic metafiles under the category folder\n :children    [\"1.welcome-to-logseq\"\n               \"2.what-is-outliner\"\n               \"3.the-third-topic\"]\n }\n```\n\n## Topics\n\nEach `Category` is composed of one or more `Topics`, and it's also the unit component of Handbook. Currently, you can create a `topic` by creating a `docs/category/xxx-topic-file.edn` metadata file in the `category` folder.\n\nA sample from `docs/1.Onboarding/1.welcome-to-logseq.edn`\n\n```clojure\n{\n ;; [Required] A friendly title for user\n :title       \"🙌 Welcome to Logseq\"\n\n ;; [Optional]\n :description \"This is a sub description text\"\n\n ;; [Optional] Some images or videos to demonstrate features\n :demos       [\"./assets/demo.png\"\n               ;; support: Local video\n               \"./assets/x.mp4\"\n               ;; support: YouTube video\n               \"https://www.youtube.com/watch?v=uig8_3kqhjY\"]\n\n ;; [Optional] This value will be auto generated from the same name markdown file. `1.welcome-to-logseq.md`\n ;; :content \"\"\n\n ;; [Optional] a thumb image for topics list\n :cover       \"./assets/demo.png\"\n\n ;; [Optional] children as chapters\n ;; If it is not set, it means that the topic has no subchapter\n :children    [\"1.welcome-to-logseq_chapter-1.edn\"\n               \"2.welcome-to-logseq_chapter-2\"]\n }\n```\n\n### What's a **Chapter**?\n\nA topic can be composed of 0 or more chapters. `Chapter` itself is also a `Topic` type.\n\n### How to write the content of topic?\n\nFor the body content of the topic, it is described by the `:content` field.\nYou can fill this field directly in the metafile, but it may be inconvenient\nwhen the content is too long, so we support that a `.md` file of the same name can also\nbe used to describe the `:content` field, which will be compiled html string during compilation.\n\n### How to link an asset file?\n\nIn order to reduce the complexity of the build logic,\n`topic` references to assets files are currently processed by convention.\nAll assets files must be placed in the `assets` folder under the corresponding `Category`.\n\n\u003e ⚠️ Since all assets files are moved to the same root directory during the build process,\n\u003e to prevent overwriting problems with files of the same name,\n\u003e you can prevent conflicts by adding a conflict-preventing prefix to the file name.\n\n### How to directly open a topic through an external link?\n\nAt present, it is supported to open the specified topic directly \nthrough the logseq scheme link like `logseq://handbook/{a-topic-fullpath-key}`.  \n\n\u003e ↪️ You can quickly get this link in this way.  [e.g. Handbook/Regular commands](logseq://handbook/3.features/commands)    \n\n![copy-pane-link.png](resources%2Fcopy-pane-link.png)\n\n### A final look at the structures of the `docs` directory!\n\n![docs](./resources/docs-structures.png)\n\n# 🛠 Set up development mode for previewing in time\n\n## Setup instructions\n1. Clone the Handbooks repo to your local machine\n2. Download and open the Handbook Logseq build and enable the developer feature in settings. A Handbook icon appears above the help button (bottom right)\n3. Click the Handbook icon and then the gear icon (⚙️) in the top right. Set the toggle **on** for **Writing mode**\n4. Open the Terminal and go to the directory where you cloned the Handbooks repo. Run the command `bb dev`\n  - For this step to run, you need to have all dependencies installed: [Java](https://www.java.com/en/) and [Babashka](https://github.com/babashka/babashka#installation)\n5. Edit the Handbook files using VS Code. Any changes you save will automatically show in the Handbook within Logseq (make sure you have writing mode enabled in the Handbook's settings)\n\n## Commands\n\n```bash\nbb dev\n```\n\nThis command will listen to the file changes under `docs/*`\nand build the handbook data to be used by the client.\n\n# ⚠️ How to publish updates to user?\n\nThe project has been configured with Github CI to deploy the latest updates,\nwhich will take effect immediately when the master branch has content changes.\nSo if you don't want the changes to take effect immediately on the Logseq client,\nyou can update the content via Github Pull Request.\n\n\u003e Online data source: https://handbooks.pages.dev/handbooks.json\n\n## Videos\n\nref link: [🔗 A video to show how to write docs](https://github.com/logseq/handbooks/issues/1)\n\n\u003cvideo width=\"100%\" height=\"auto\" controls\u003e\n  \u003csource src=\"https://user-images.githubusercontent.com/1779837/217492648-d1cba1ad-9c35-48b2-9ba1-ed26f70b1efd.mp4\" type=\"video/mp4\"\u003e\n\u003c/video\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogseq%2Fhandbooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flogseq%2Fhandbooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogseq%2Fhandbooks/lists"}