Metadata-Version: 2.4
Name: obsidown
Version: 0.2.9
Summary: A quick way to convert obsidian markdown docs to markdown static pages
License: GPL-3.0-only
License-File: LICENSE
Author: Angelo 'Flecart' Huang
Author-email: xuanqiang.huang@studio.unibo.it
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: bibtexparser (>=2.0.0b7,<3.0.0)
Requires-Dist: gitpython (>=3.1.44,<4.0.0)
Requires-Dist: pydantic (>=2.6.3,<3.0.0)
Requires-Dist: python-frontmatter (>=1.1.0,<2.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Project-URL: Homepage, https://pypi.org/project/obsidown/
Project-URL: Repository, https://github.com/flecart/obsidown
Description-Content-Type: text/markdown

# ObsiDown

Convert obsidian files into well linked markdowns!

## Example use cases
- Export Obsidian subdirectories while maintaining the links in markdown format
- Make obsidian math Kramdown-compatible
- Use obsidian to write for Jekyll web pages. 

## How to use

Define a configuration file `config.yaml`. In the repo it is provided one as example.
Install the `poetry` dependencies and then you just need to run `poetry run python -m obsidown --config path/to/config.yaml`

It's possible to install from `pypi` index by `pip install obsidown`.
Then you can run it with `python -m obsidown`

## Feedback

This project is a hobby project used to automate some things I use myself. Currently it is a early early project!
If you need additional features or report some issues or need help, feel free to open a new issue.

## Documentation

The quickest way to check what is the format of the config file is to see the pydantic from `config.py`.
Here I will just outline it briefly.

- `sources` defines where to look for the input files.
  - `paths`: where to look for the md files?
  - `images`: where to look for the linked images?
- `output` defines where to write the exported files.
  - `base`: defines the base url for links
  - `path`: defines a subpath for the markdown files
  - `images`: defines a subpath for the image fiiles
  - `filesystem`: where to write
- `pipeline`: defines the single operations possible on a markdown file.
  - `name`: the identifier of the operation, you should check `dispatch.py` for a list of the operations.
  - `options`: variable options of the single operation.

### Configuration Reference

Below is a more complete configuration example that you can adapt to your vault:

```yaml
sources:
  paths:
    - /path/to/obsidian/notes
  images:
    - /path/to/obsidian/assets
output:
  base: notes
  path: content/notes
  images: images/notes
  images_path: static/images/notes
  filesystem: /var/www/my-site
pipeline:
  - name: remove_after_string
    options:
      string: "# Private Section"
  - name: remove_single_char_lines
    options:
      character: "-"
  - name: update_frontmatter
    options:
      frontmatter:
        ShowToc: true
        TocOpen: false
  - name: link_convert
    options: {}
  - name: write_file
    options: {}
```

Some useful pipeline operations and their options:

- `remove_after_string`: drop content after the first occurrence of `string`. Set `line: true` to remove just the matching line portion.
- `remove_single_char_lines`: remove lines entirely made of repetitions of a single `character` (for example Obsidian separators like `-----`).
- `update_frontmatter`: merge or override metadata by passing a `frontmatter` dictionary.
- `citation_convert`: convert citations with `bibfile` pointing to a Zotero/BibTeX export.
- `link_convert`: translate Obsidian `[[wikilinks]]` into absolute links according to `output.base`.
- `write_file`: persisting step that writes the transformed file in the configured destination.

You can chain as many operations as you need; each one receives the output of the previous step, so ordering matters.
