Please cite the following if you use it for publishable work (i.e., if you write your paper in Obsidian, and use this code to print to Latex)
@misc{MariosGkionisObsidian2Latex,
author = {Marios Gkionis},
title = {Straightforward Obsidian to Latex},
year = {2023},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/MariosGkMeng/Straightforward-Obsidian2Latex}},
}
(navigate to next section if you want to skip the "sales pitch")
Want to write your documents entirely in Obsidian, and then print them to LateX (e.g., for scientific papers and lab reports)? Are you annoyed by:
- The fact that you have to write code, just to make a nice report/paper?
- How incomplete the "print to .pdf" command in Obsidian is?
Do you just want to be able to seamlessly write formal content in the same software as your notes, and print it from there, without the need to move to external software? Or do you just want to write pretty scientific documents without needing to learn Latex at all (with the exception of the equation environment)?
This Obsidian to Latex translator is complete, straightforward to use, and has no 🐂💩 unnecessary complexity as an end result.
It is the most complete that I have seen among existing ones, since it offers more niche functionalities, such as:
- Correct table conversion
- Unfolding content of embedded notes (other packages I have seen just keep the "![[embedded_note]]" in the final text, when in reality the content of that note should appear in the LateX file)
- NEW: Conditional Formatting Rules
Yes, plugins for Obsidian to Latex already exist, but they have limitations that do not allow the user to write in Obsidian freely. Yes, I'd have loved to contribute to those projects, but I don't know Javascript and Typescript.
I consider LateX a very archaeic tool, not suited for the intense knowledge-work of 2024. It is clunky, and forces the researcher to write code, when they just want to write about their work 😩 I want to see it not being used at all, but due to its legacy, I doubt it will happen any time soon. So, what we are left with is the need to translate content from proper tools (like Obsidian) to not-so-good old LateX.
- Tables
- Long tables (tables that can expand to more than 1 pages)
- Non-long tables
- Special formatting for each table (different package, coloring of rows)
- Internal links (sections and blocks)
- External links
- Sections and subsections
- Maintain proper hierarchy of sections of the main note when a note with sections is embedded
- Image/figure display with appropriate figure referencing, captions, and size in LateX
- Bullet lists
- Numbered lists
- References/bibliography
- But so far only with my own referencing method
- Embedded notes
- Inluding section hierarchization (i.e., keeping track on what level of section the embedded note was, thus converting any sections inside it to subsections that adhere to the initial hierarchy
- Equations (although the equations in Obsidian are exactly the same as in Latex)
- Numbered equations
- Discard of text that is inside comments
- Bold font
- Highlighted font
- Removal of Obsidian Comments
- Specific parts of embedded notes (e.g. if the embedded note is "![[note_name# Some note section]]", the script would still paste the entire content of that note)
- Convertion of codeblocks (including inline code)
- Italic font
- Admonition blocks (I use that quite frequently, because it is very pleasant for the eye)
- Captions for figures (will use the note-block logic, as in the Equation Referencing)
- Figure size
- Subplots
- Conditional Formatting: colored text for notes that contain specific tag(s)
- Graphs with the latex plotting environment (won't be developing that soon, since most people use .pdf files for figures anyways)
- Desirable placement for images
- Subplots (so far figures only have one plot)
- Switching from 2 columns to 1 column per page (or any column number switch for that matter) --> needs a short "command language" for when the user is writing in Obsidian
- Formatting certain words based on rules
- Examples
- Format text of mentioned notes based on
- their path (e.g., path with methods)
- [X]tags therein
- Discard text inside comments after start of a (sub)section
- Properly convert results from querying commands in Obsidian. This will probably never be achieved with this converter, since it requires to have access to the obsidian dataview and dataviewjs outputs.
- VERY DIFFICULT: Convert anything that has to do with dataview, dataviewjs and inline queries.
- This would be very useful, since dataview(js) is quite a powerful tool for organization of numerous things. An idea would be to convert it to .pdf, and merge it to the LateX file. Otherwise, a lot of programming is required!
- Automatic table size manipulation (not even LateX does that itself)
- Regarding Internal links: add page number next to the cross-reference, in case the document is printed
- EMOJIS: Latex does not include emojis. Therefore, so far they are replaced by text, however in the future I am considering to convert them to small pictures
- Code maintenance
- Creating warning messages for errors that the user makes when writing the note
- More niche table conversions
In this section, I will be writing what actions will cause errors in this version of the code.
- Writing equations outside of the equation-block notes (read here). A correct conversion happens only when the equations are inside these special note files.
- Writing tables and figures outside of their designated table-block and figure-block notes (same as with the equations)
- Writing text using underscores without the escape character ("_" instead of "_"), unless written in specific environments, such as equations
- Having the following characters appear an odd number of times in the document: a. "**" b. "*" c. "=="
- Equations:
- The equation-referencing system helps reference the equations using the note-linking feature, thus allowing perfect traceability of the equations. The user can reference the equations in Obsidian and click/hover on their link to view them! See short video for a quick demonstration.
- In addition, if you change the name of the equation, because it is a note, any references to it will be updated!
- The equation-referencing system helps reference the equations using the note-linking feature, thus allowing perfect traceability of the equations. The user can reference the equations in Obsidian and click/hover on their link to view them! See short video for a quick demonstration.
- Fast conversion: Conversion to LateX is fast when the user allows the program to first find the note paths, log them in a textfile, and then not search for them again (unless moved to another folder, or have their names changed, in which case the tool searches anew within the vault)
- Works seamlessly with embedded notes. The benefits of using embedded notes are enlisted here
- Erases Obsidian Comments
- Large Obsidian files consume significant RAM (read here as to why)
- Equation referencing: so far need to create separate embedded notes that represent equation blocks, since Obsidian itself cannot interact with MathJax well enough to create an equation referencing system
- ⚠ Direct text replacements are not possible, since we are using embedded notes, therefore those texts that we want to replace are not found in a single document (a solution can implemented, via tracking the links)
- Solution: Use the text replacement tool in
converter.py.
- Solution: Use the text replacement tool in
If you want to jump to some videos, here's the list:
| create equation block for referencing | create equation block for referencing |
| convert and see the result in LateX | convert and see the result in LateX |
| why this conversion system is very convenient | why this conversion system is very convenient |
| how to write equations quickly | Much faster than vanilla LateX, or vanilla Obsidian! |
- Have Python 3 installed
- Have Obsidian installed
- Install the following Obsidian plugins
- Helps speed up equation referencing: QuickAdd (for quick insert of equation blocks)
- Optional, helps write equations very fast: Quick Latex for Obsidian
Go to converter.py. You only have to deal with that.
You should only change things in the 'PARS' dictionary, which contains all the settings.
To set the paths for the .md file to be converted, inside converter.py, under "User Parameters" section, change the:
- PATHS['command_note']. It corresponds to the path of
👨💻convert_to_latex.md.
You won't need to change anything else inside converter.py, since the other paths are given in 👨💻convert_to_latex.md.
👨💻convert_to_latex.md contains the instructions inside commands.
You can use the example vault in order to see how the converter works, and a showcase of what it can convert. The only modification you will need to do in order to use the vault as I intended to is to rename the "obsidian" folder to ".obsidian", since the latter name implies a hidden folder, github does not allow me to upload it, therefore I had to rename it.
In 👨💻convert_to_latex.md, click on the links next to the code_run:: field. The 1st command performs the conversion from Obsidian to Latex, the 2nd compiles the latex file to .pdf.
This uses what we can call "==note-block logic==". I.e., writing the equation in a single note, but without writing anything else in that note (hence the "block" part of the name). We will use the same logic for Tables and Figures, so that their referencing becomes easier, and automatic upon name changes.
Due to the inherent difficulty of equation numbering in Obsidian (read this thread for details), there is no direct way to number and refer to the equations in Obsidian.
The workaround that I have used requires creation of a separate note wherein only the equation is to be added. The note has to obey a few formatting rules, which can be automated with QuickAdd. To learn how to use it, please refer to the plugin guide. It is quite easy.
The folder that you specify in QuickAdd wherein your equation note/block is to be created must be the same as PARS['📂']['equation_blocks'].
- Name: The equations are to be labeled based on the name of the note. Therefore, for the code to be able to recognize them easily, I have created a name-based rule. If you wish to name the equation "conversion_law", then the name of the note should be "eq__block_conversion_law". Then, when in your document you refer to this equation, you can simply write "in equation [[eq__block_conversion_law]]", and the final latex text would be "in equation \ref{conversion_law}".
- Structure: The note has to only have that equation inside, and nothing else!. It is recommended that you start with a section "# %% expr %%" and then add the equation, such that you can embed it like ![[eq__block_conversion_law#expr]]. That way, the title of the note is not visible, making the obsidian file more readable.
- Path: use a path of your choosing to put those equations. The reason for this is that in case you have a large vault, the code would have to search for the path of that note within the entire vault. Specifying a path for the equation blocks saves time.
Those steps above would normally require manual work, which would be annoying.
A way to automatically create an equation-note with the right format, in the right folder is to use the QUICKADD community plugin.
📽 The videos below illustrate how it creates those automatic equation notes, reference them, and how it looks in LateX.
example__embed_equation_based_on_correct_format.mp4
change_equation_reference_name_and_refer_to_it.mp4
Maintains_perfect_traceability.mp4
So far, I am using my own system for citations in my Obsidian notes.
Specifically, each time I download a .pdf file that contains an article/book, I name it "62. TitleOfPaperOrBook, YYYY.pdf", where YYYY is the year in the YYYY format, and "62" is the sequence number (i.e., the 62nd article/book I have in that folder).
Then, I use a note: [[p62]] to represent that paper. And now, the conversion works as follows:
Obsidian Text: "In [[p62]], the authors mention that ..." Latex Text: "In \cite{p62}, the authors mention that ..."
BUT: as a user, you have to add the BibTex citation manually in your designated BibTex file, and use the "p62" as a name. That Bibtex file should be located in the same path as PARS['📁']['tex-file']!
I will "relax"/parameterize this rule soon.
Read in the Obsidian website for information on what they are.
Embedded notes allow us to:
- Make our work modular
- Reuse notes, i.e., making them repeatable --> no need to manually copy/paste and rewrite things!
- Index the content of these notes (with more linked notes and/or tags) that apply only on that note --> doing that helps make the search for this note based on the indexing easier
- Focus on specific small parts of a document, instead of searching it in large stand-alone documents
- Use Obsidian for what it was made: creation of a knowledge structure: this means that smaller blocks of information are linked to each other based on their relationships and the meaning that they have to the creator. Therefore, writing a large document without embedded notes would result in you missing out in one of the most important features of Knowledge Management
Basically, the QuickAdd community plugin creates new notes based on user specified templates. You can make it place that note in specific folder, specify naming convention for that note, and a few other functionalities.
Install the "Quick Latex for Obsidian" Community plugin. You can write your own snippets (see video below, wherein I show a few of my own as examples).
🔋🔋🔋 This makes equation writing much faster than vanilla LateX, or vanilla Obsidian!
📽 see video below on how fast you can write equations!
⚠ For the equation snippets, don't forget to press the Space key after inserting them (not mentioned in the video)
Write.equations.very.quickly.mp4
(➕under construction)
| This repo | Pandoc Plugin | Copy as Latex | Enhancing Export | |
|---|---|---|---|---|
| Embedded notes | ✔ | ❌ | ❌ | not running for me |
| Equations | ✔ | ❌❓ --> maybe not, was not able to do it so far | ✔ | not running for me |
| Equation referencing | ✔ | ❌ (seems to not be working) | ❌ | not running for me |
| Is fast | ✔ (but only when most of the embedded references are listed in PARS['📂']['list_paths_notes']) |
✔✔ | ✔✔ | not running for me |
| Ignores comments | ✔ | ✔ | ✔ | not running for me |
- Add a toy-vault with the appropriate paths and folders --> adjust the paths in the code accordingly
- Add comments within the note for the user to learn interactively
- Add video to show how the figure system works
- Add video to show how the admonition system works