Converts Obsidian style markdown files to Org-Mode files using pandoc.
Project description
Obs2Org
Obs2Org is a cross platform command (works on *BSD, Linux, OS X and Windows) line program to convert Obsidian style Markdown files to Org-Mode files for Emacs and other Editors that support Org-Mode.
It converts the Markdown files using Pandoc and afterwards corrects the links to headings in other Org-Mode files, converts the hash-tag style Obsidian tags to Org-Mode style tags and puts angle brackets around dates.
Example
Obs2Org converts a Markdown file like to following:
---
title: "Programming"
author:
-
keywords:
- Programming
tags:
- Programming
lang: en
---
# Programming
Keywords: #Programming
## Lisp
### Books
Keywords: #Lisp, #Book
- Lisp Cookbook, 'recipies' to solve common problems using Lisp: [[Books#Lisp Cookbook]]
- **Peter Seibel**: *Practical Common Lisp*: [[Books#Practical Common Lisp]]
- **Peter Norvig**: *Paradigms of Artificial Intelligence Programming: Case Studies in Common Lisp*: [[Books#Paradigms of Artificial Intelligence Programming]]
### State of the Common Lisp ecosystem, 2020
2021-10-08
Keywords: #Lisp, #Ecosystem, #2020
Editors, libraries, compilers, ...
[State of the Common Lisp ecosystem, 2020](https://lisp-journey.gitlab.io/blog/state-of-the-common-lisp-ecosystem-2020/#development)
to the following Org-Mode file:
#+title: Programming
* Programming :Programming:
:PROPERTIES:
:CUSTOM_ID: programming
:END:
* Lisp
:PROPERTIES:
:CUSTOM_ID: lisp
:END:
*** Books :Lisp:Book:
:PROPERTIES:
:CUSTOM_ID: bücher-1
:END:
- Lisp Cookbook, 'recipies' to solve common problems using Lisp: [[file:Books.org::#lisp-cookbook][Lisp Cookbook]]
- *Peter Seibel*: /Practical Common Lisp/: [[file:Books.org::#practical-common-lisp][Practical Common Lisp]]
- *Peter Norvig*: /Paradigms of Artificial Intelligence Programming: Case Studies in Common Lisp/: [[file:Books.org::#paradigms-of-artificial-intelligence-programming][Paradigms of Artificial Intelligence Programming]]
*** State of the Common Lisp ecosystem, 2020 :Lisp:Ecosystem:2020:
:PROPERTIES:
:CUSTOM_ID: state-of-the-common-lisp-ecosystem-2020
:END:
<2021-10-08>
Editors, libraries, compilers, ... [[https://lisp-journey.gitlab.io/blog/state-of-the-common-lisp-ecosystem-2020/#development][State of the Common Lisp ecosystem, 2020]]
See Installation and Usage for information on how to do that.
The PyPI (pip) package can be found at Obs2Org at PyPI
Additional Documentation can be found at Read the Docs
Table of Contents
Installation
Pandoc
Pandoc is needed to do the actual conversion of Markdown files to Org-Mode files.
See Installing pandoc on how to install Pandoc for your OS.
Obs2Org
Python, at Least Version 3.9
The PyPI Obs2Org Package
Install the PyPI (pip) package obs2org
for all users on your computer as administrator/root:
-
Linux, OS X:
sudo pip install obs2org
-
Windows:
Open an administrator shell by writing
cmd
in the search field of the taskbar, ricght click on the command app and select "Run as Adminsitrator". in this shell execute:pip install obs2org
Usage
Use Obs2Org by running it as a normal user (not administrator or root) as Python module using
-
Linux, OSX:
python3 -m obs2org --version
-
Windows
python -m obs2org --version
This should yield the version string like
> python -m obs2org --version
obs2org 1.2.0
To get a text explaining the usage of Obs2Org, use the argument --help
or the short form -h
:
Windows:
python -m obs2org --help
Linux, OS X:
python3 -m obs2org --help
Output:
> python -m obs2org --help
usage: python -m obs2org [-h] [-V] [-p PANDOC] [-n] [-u] [-o OUT_PATH] [MARKDOWN_FILES ...]
Converts markdown formatted files to Org-Mode formatted files using Pandoc.
positional arguments:
MARKDOWN_FILES The path to the markdown files or directory to convert to
...
Examples
These examples only work if Pandoc is in the PATH of your shell. If it isn't you can add the path to Pandoc by using the argument --pandoc
or -p
.
To set the path to Pandoc to c:/pandoc/pandoc
add --pandoc c:/pandoc/pandoc
or -p c:/pandoc/pandoc
to each invocation of Obs2Org.
Example:
python -m obs2org ./Markdown -o ../Org/ --pandoc c:/pandoc/pandoc
-
current directory
python -m obs2org
Which is the same as
python -m obs2org ./
Converts all markdown files with a suffix of
.md
in the current working directory and all its subdirectories to files in Org-Mode format with the same base filename but a.org
suffix. -
one file
python -m obs2org hugo.md -o sepp.org
Converts the markdown document
hugo.md
to an Org-Mode document namedsepp.org
. -
all files with extension
.md
python -m obs2org *.md
Converts all markdown files with a suffix of
.md
in the current working directory to files in Org-Mode format with the same base filename but a.org
suffix. -
convert files to given directory
python -m obs2org *.md -o ../Org/
Converts all markdown files with a suffix of
.md
in the current working directory to files in Org-Mode format with the same base filename but a.org
suffix in the directory../Org
. The directory to save to must have a slash/
at the end. -
convert files in given directory to other directory
python -m obs2org ./Markdown -o ../Org/
Converts all markdown files with a suffix of
.md
in the directory./Markdown
and its subdirectories to files in Org-Mode format with the same base filename but a.org
suffix in the directory../Org
. The directory to save to must have a slash/
at the end. -
Add UUID file headers to any file that doesn't already have one - flag
-u
or--uuid
:python -m obs2org ./Markdown -o ../Org/ -u
Converts all markdown files with a suffix of
.md
in the directory./Markdown
and its subdirectories to files in Org-Mode format with the same base filename but a.org
suffix in the directory../Org
. Add file headers with an UUID if not already present. The directory to save to must have a slash/
at the end. -
Treat Pandoc-style citation links as normal links - flag
-n
or--no-cite
:python -m obs2org ./Markdown -o ../Org/ -n
Converts all markdown files with a suffix of
.md
in the directory./Markdown
and its subdirectories to files in Org-Mode format with the same base filename but a.org
suffix in the directory../Org
. Treat links like[[@Name]]
as normal link to a file@Name.org
instead of Pandoc-style citation[[cite:@Link]]
. The directory to save to must have a slash/
at the end.
Supported Links
The following list shows which Markdown links are converted to which Org-Mode links:
[[books#My Heading]]
is changed to[[file:books.org::#my-heading][My Heading]]
.[[Note]]
is changed to[[file:Note.org::#note][Note]]
.[[#heading-id|Caption]]
is changed to[[#heading-id][Caption]]
[[file|Caption]]
is changed to[[file][Caption]]
[[#Heading]]
is changed to[[*Heading]]
- if
-n
or--no-cite
is set, a Pandoc citation is treated as a normal link:[[@Link]]
is changed to[[file:@Link.org][Link]]
- as default Pandoc citation links are converted to citation links:
[[@Link]]
is changed to[[cite:@Link]]
Development
Python, version > 3.9
You need Python 3.9 or newer.
Setup
-
Run
pipenv install --dev
to install the Python environment in the project directory -
Run
pipenv run pre-commit install
to install the pre commit hooks to git. Now every time you commit a change, the linters are run.- To run the pre commit checks manually:
pipenv run pre-commit run --all-files
- To run the pre commit checks manually:
Scripts
- ./make_package.sh - Linux, OS X: build the Obs2Org PyPI package
- ./make_package.bat - Windows: build the Obs2Org PyPI package. This is disabled on Windows, because the scripts would not be executable because of the Windows filesystem.
- ./run_local_linters.sh - Linux, OS X: run all configured linters on the Source code and tests.
- ./run_local_linters.bat - Windows: run all configured linters on the Source code and tests.
- ./run_tests.sh - Linux, OS X: run all tests.
- ./run_tests.bat - Windows: run all tests.
Documentation
Ths source files for the Read the Docs site are located in the directory ./obs2org/doc/source
Sources
The sources of the program are in the directory ./obs2org/, the test sources and fixtures in ./tests/
License
Obs2Org ist licensed under the GPLv3.0, see file LICENCE.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.