-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
d596fed
commit c1470c9
Showing
1 changed file
with
49 additions
and
29 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,55 +1,75 @@ | ||
| # Markdown Converter and Outliner | ||
| # Markdown Converter and Outliner for migration from Obsidian to Logseq | ||
|
|
||
| ## Purpose | ||
| [Obsidian](https://obsidian.md) and [Logseq](https://logseq.com) are two popular note-taking applications. While both applications use Markdown, they have different syntax and structure requirements. This project aims to provide tools to convert Markdown documents from Obsidian to Logseq format to facilitate migration between the two applications. | ||
|
|
||
| This project provides tools to convert Markdown documents from Obsidian-flavored Markdown to Logseq's org-mode inspired Markdown. It includes two main scripts: `translate.ts` and `outliner.ts`, along with their respective test files. The project also includes documentation on the structural and syntactical differences between Obsidian and Logseq. | ||
| There are surprisingly a lot of differences and nuances, so I made this tool to automate the process and I'm sharing it in case it helps someone else. | ||
|
|
||
| ## Design | ||
| ## Features | ||
|
|
||
| ### Scripts | ||
| - **Syntax Translation**: Converts various Markdown elements such as tasks, highlights, wiki-links, embeds, block quotes, callouts, and frontmatter from Obsidian to Logseq format. | ||
| - **Tasks**: Converts the syntax from the popular Obsidian Tasks plugin to Logseq org-mode tasks, including dates and priorities. | ||
| - For the full list of syntax differences, see [syntax-differences.md](syntax-differences.md). | ||
| - **Structure Outlining**: Converts the flat structure of Markdown documents into a nested list structure suitable for Logseq. | ||
| - The structure implied by the headings in the document is converted into an outline native to Logseq. | ||
| - For the explanation see [structure-difference.md](structure-difference.md). | ||
| - **Daily Notes**: Automatically converts Obsidian daily notes to Logseq journal notes. | ||
|
|
||
| 1. **[translate.ts](translate.ts)**: This script handles the conversion of various Markdown elements such as tasks, highlights, wiki-links, embeds, block quotes, callouts, and frontmatter from Obsidian to Logseq format. | ||
| 2. **[outliner.ts](outliner.ts)**: This script converts the flat structure of Markdown documents into a nested list structure suitable for Logseq. | ||
| ## Motivation | ||
|
|
||
| ### Documentation | ||
| Logseq advertises that you can simply point it to your folder with Markdown files and it will work, but the reality is that it will not understand some of the Markdown syntax and will treat the base structure of the files as a flat list. Logseq also changes files by treating all content as an outline which messes up the original structure and makes it harder to work with files in other applications. | ||
|
|
||
| 1. **[structure-difference.md](structure-difference.md)**: This document explains the structural differences between Obsidian and Logseq and provides guidelines on how to convert documents to maintain the intended structure. | ||
| 2. **[syntax-differences.md](syntax-differences.md)**: This document details the syntactical differences between Obsidian and Logseq Markdown, including tasks, wiki-links, frontmatter, block quotes, callouts, and embeds. | ||
| While you can [make Obsidian play nicely with Logseq](https://discuss.logseq.com/t/making-obsidian-play-nice-with-logseq/1185), it doesn't go the other way around. So this project aims to provide a way to migrate to the format that Logseq expects to take full advantage of its features, then decide whether to keep using Logseq or not. | ||
|
|
||
| ## Usage Instructions | ||
| ## Usage | ||
|
|
||
| ### `translate.ts` | ||
| > [!WARNING] | ||
| > | ||
| > This project is still in development and may not be completely reliable. Use it at your own risk and always make backups of your files. | ||
| > | ||
| > Also, documentation may be lacking, but don't hesitate to ask for help in the [discussions](https://github.com/laughedelic/outbreak/discussions/new?category=q-a) | ||
| To convert a Markdown file from Obsidian to Logseq format, run the following command: | ||
| Until there are release binaries, you need to have [Deno](https://deno.land) runtime installed on your system, and you need to clone this repository to have the scripts available locally. Once that is done and you are in the cloned repository, you can run it with the following command: | ||
|
|
||
| ```sh | ||
| deno run translate.ts <input-file> <output-file> | ||
| deno run outbreak.ts <obsidian-vault-path> <output-path> | ||
| ``` | ||
|
|
||
| ### `outliner.ts` | ||
| Thanks to the secure Deno runtime, the script will *explicitly ask you for permissions* to read the input files (not modify!) and write the output files. So you know that you are not giving these scipts access to do anything else. It will then plan the migration, *show you the summary*, and ask for confirmation before proceeding. There is also a `--dry-run` flag that you can use to see the plan without actually writing any files. | ||
|
|
||
| To convert a Markdown file from a flat structure to a nested list structure suitable for Logseq, run the following command: | ||
| After you run the migration, you can open the destination folder in Logseq and see the results. If you run it more than once (e.g. after some adjustments), you should re-index the folder in Logseq to make sure it picks up the changes. | ||
|
|
||
| ```sh | ||
| deno run outliner.ts <input-file> <output-file> | ||
| ``` | ||
| > [!IMPORTANT] | ||
| > | ||
| > Output files will be created or overwritten (!), so don't point it at your existing Logseq graph folder. | ||
| > Always try it on a new folder first. If you like the results, you can then copy the files to your main Logseq graph. | ||
| > [!TIP] | ||
| > | ||
| > It is recommended to use [Obsidian Linter](https://github.com/platers/obsidian-linter) plugin to clean up your Obsidian Markdown before committing to the migration. This will help to avoid some potential issues with inconsistent formatting. | ||
| > [!NOTE] | ||
| > | ||
| > There is a lot of potential for configurability and customization in this tool. At the moment it's just tuned to my personal needs, but I want to expose the configuration to make it more flexible and useful for others. | ||
| > | ||
| > For now, you can modify the in-code configuration directly to adjust the behavior. | ||
| ## Development instructions | ||
|
|
||
| 1. Setup: Ensure you have Deno installed on your system. | ||
| 2. Run tests: | ||
|
|
||
| ```sh | ||
| deno test | ||
| ``` | ||
| ```sh | ||
| deno test | ||
| ``` | ||
|
|
||
| 3. Linting and formatting: | ||
|
|
||
| ```sh | ||
| deno lint | ||
| deno fmt | ||
| ``` | ||
|
|
||
| ## License | ||
| ```sh | ||
| deno lint | ||
| deno fmt | ||
| ``` | ||
|
|
||
| > [!TODO] add an open-source license, probably LGPL or MPL | ||
| > [!TIP] | ||
| > | ||
| > Contributions are welcome! Take a look at the [TODO.md](TODO.md) file and any `TODO` comments in the code. | ||
| > Open a new [discussion](https://github.com/laughedelic/outbreak/discussions/new?category=ideas) to plan the implementation or suggest your ideas. |