Writing manuals in Obsidian

Hi all. I ask for advice and help about writing instructions in Obsidian and then exporting them to PDF. At work, I often have to write instructions for users on how to use the software, and they contain quite a lot of images. At the moment, I write most of the instructions in Notinon, but I decided to try to switch completely to Obsidian. While working at Obsidian, I encountered various inconveniences.

Resizing images and positioning them on the sheet
In Notinon, I resized the images with the mouse and visually chose the size that I needed. In Obsidian I have to change the size by manually entering the image size in pixels or percentages, and this is not always convenient. I tried using the “Mousewheel image zoom” plugin, but unfortunately it doesn’t always work when I use CSS snippets to insert multiple images horizontally. Also, after inserting several images horizontally, there may be problems with exporting to PDF.

Export to PDF
After exporting to PDF, it happens that some of the elements may not be displayed in the document, the image sizes are reset. Some of the text may be on one page, but the image is already on another page.

1 Like

Just a thought, but would it be an option to just export the markdown vault in itself?

I mean, help documentation has traditionally been prsented using its own software, so why in recent times do that software need to be a pdf viewer, and not Obsidian?

Another pro, is that with markdown the end user would be capable of editing and extending their own documentation to their own specifications.

Back to your request they both seem to arise when combining multiple images using markdown. Wouldn’t combining the images before inclusion in the target document solve both issues? In other words, if you found a plugin (or external editor) to combine images into a single image, your current workflow seems to work.

Suggestion: use ASCIIDOC. WAAAAY better for tech docs than MD. Edit in Visual studio with the AD plugin.

Is that possible? exporting the entire markdown vault and host it online as documentations?

@7yang7 Exporting pdf from obsidian suck. I tried and encountered many problems.

  • obsidian doesn’t support pagination, you don’t know precisely where the page start and end, markdown is endless text, and your text would be trimmed in places you have no control over.
  • the pain of images while exporting the note to PDF
  • the pain of trying to align image or table in some position

My current workaround is to write it in markdown then export it to doc format, edit it and print it to PDF. Of course this is to many manual work, also you lose the beautiful decorations and styles obsidian’s themes offer.


Is that possible? exporting the entire markdown vault and host it online as documentations?

Yes, using Obsidian Publish. Obsidian Publish

Obsidian Publish is good but I was expecting a static website. Like if you wrote a library and want to share the documentation as static pages on the library website.

Publish is a static web site, is it not?

Just to drop it in here:

another workaround would certainly be to not directly export to pdf, but to export to docx or odt first (possible with the pandoc plugin). You could then rearrange your file once to meet your layout requirements and finally export it to pdf directly from Word, LibreOffice etc.

Thanks, I didn’t know about ASCIIDOC. Yesterday I tried to create a document and export it, I had difficulties with the separate positioning of headings, blocks of text and images. I tried to find how to describe all this in the title of the document, but unfortunately I did not find it.

1 Like

I wanted to avoid exporting to odt, doc, docx and immediately get a beautiful and concise document, but apparently this is not so easy, unfortunately.


Today I learned one more feature ASCIIDOC, to use third-party fonts, to center all images in the entire document at once, to export to PDF, you need to create separate configuration files.

1 Like

ASCIIDoctor has all the config files written for you. As does the AD plugin for Visual Studio. As does ASCIIDOCFX. SO you really don’t need to touch any of that unless you want. They can all produce PDF’s from one click.

From Visual Studio a PDF is generated without any problems, I tested it. But to use a different font and make all the images in the document center by default, you need to create your own configuration.

Unfortunately obsidian doesn’t support exporting PDF perfectly, I wish for obsidian to have a somewhat live view of PDF. Somewhat like overleaf the laTeX online editor if you used it before.
The ability to see where page start and end and also preserve the theme of obsidian.
That would be a dream. export books, technical papers and D&D papers with stylized theme.

All of that can happen if they support a live re/compile of PDF files while editing then saving the markdown file.

It is, but you need to host it on Obsidian Publish, I was talking about writing documentations for a program or a programming library and then upload the entire markdown vault to that program or a programming library own website.

You can easily host MD files anywhere you want. ?

The whole point of obsidian is what it add to .md files from theme and style to code highlighting and rendering the whole markdown grammars.

I want the vault to be generated with the theme, if you saw Obsidian Publish sites you would understand what I want. Exporting the file with its theme (the theme being used in Obsidian) as static HTML file.

Yes, I can host .md file but then I would need javascript library to render it, porting the theme I use from Obsidian to the web.

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.