| Name | obsipub JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | Convert Obsidian vaults to EPUB format with proper chapter structure |
| upload_time | 2025-07-13 20:00:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License
Copyright (c) 2025 TCSenpai
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
obsidian
epub
ebook
markdown
converter
knowledge-base
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
PyYAML
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Obsipub
Convert your Obsidian knowledge base to beautifully formatted EPUB ebooks with proper chapter structure and attachment handling.
## Features
🔧 **Smart Processing**
- Bulletproof YAML front matter handling
- Wikilink conversion to standard markdown links
- Automatic attachment processing and inclusion
- Hidden/system file exclusion (.git, .obsidian, etc.)
📚 **Perfect EPUB Structure**
- Folders become chapters with proper heading hierarchy
- Notes become sections with shifted headers for clean TOC
- Automatic table of contents generation
- Proper metadata handling
🎯 **Flexible Options**
- Include or exclude attachments
- Keep or remove Obsidian tags
- Custom book title and author
- Verbose logging for debugging
## Installation
### From PyPI (recommended)
```bash
pip install obsipub
```
### From Source
```bash
git clone https://github.com/yourusername/obsipub.git
cd obsipub
pip install -e .
```
## Requirements
- Python 3.7+
- [Pandoc](https://pandoc.org/installing.html) (for EPUB generation)
### Installing Pandoc
**Ubuntu/Debian:**
```bash
sudo apt install pandoc
```
**macOS:**
```bash
brew install pandoc
```
**Windows:**
Download from [pandoc.org](https://pandoc.org/installing.html)
## Quick Start
### Command Line Usage
```bash
# Basic conversion
obsipub /path/to/obsidian/vault output.epub
# With custom title and author
obsipub /path/to/vault mybook.epub --title "My Knowledge Base" --author "Your Name"
# Exclude attachments and keep tags
obsipub /path/to/vault book.epub --no-attachments --include-tags
# Verbose output for debugging
obsipub /path/to/vault book.epub --verbose
```
### Python API Usage
```python
from obsipub import ObsidianToEpubConverter
# Basic usage
converter = ObsidianToEpubConverter(
vault_path="/path/to/obsidian/vault",
output_epub_path="output.epub",
title="My Knowledge Base",
author="Your Name"
)
success = converter.convert()
if success:
print("Conversion completed!")
else:
print("Conversion failed - check warning.log")
# Advanced usage with options
converter = ObsidianToEpubConverter(
vault_path="/path/to/vault",
output_epub_path="book.epub",
title="Advanced Guide",
author="Expert Author",
include_attachments=True, # Include images and files
include_tags=False # Remove #tags from content
)
converter.convert()
```
## How It Works
### File Processing
1. **Scanning**: Recursively scans your vault, ignoring system directories
2. **Structure**: Maps folder hierarchy to EPUB chapter structure
3. **Processing**: Handles YAML front matter, wikilinks, and attachments
4. **Generation**: Uses Pandoc to create the final EPUB
### Heading Hierarchy
```
Folder/ → # Chapter (H1)
├── Subfolder/ → ## Subchapter (H2)
│ ├── Note.md → ### Note Title (H3)
│ │ ├── # Header → #### Header (H4)
│ │ └── ## Subheader → ##### Subheader (H5)
```
### What Gets Processed
- ✅ Markdown files (.md)
- ✅ Images (PNG, JPG, GIF, etc.)
- ✅ Documents (PDF, DOCX, etc.)
- ✅ Wikilinks `[[Note Name]]`
- ✅ Attachments `![[image.png]]`
### What Gets Excluded
- ❌ Hidden directories (`.obsidian`, `.git`, `.trash`)
- ❌ System files (`.DS_Store`, `Thumbs.db`)
- ❌ Temporary files (`.tmp`, `.log`, `.pyc`)
## Command Line Options
```bash
obsipub [-h] [--title TITLE] [--author AUTHOR] [--no-attachments]
[--include-tags] [--verbose] [--version]
vault_path output_epub_path
```
### Arguments
- `vault_path`: Path to your Obsidian vault directory
- `output_epub_path`: Where to save the generated EPUB file
### Options
- `--title`: Custom book title (default: "Obsidian Vault")
- `--author`: Book author name
- `--no-attachments`: Skip including images and attachments
- `--include-tags`: Keep Obsidian tags like `#important` in text
- `--verbose`: Enable detailed logging output
- `--version`: Show version information
## Examples
### Convert Specific Subfolder
```bash
# Convert only your "Projects" folder
obsipub "/path/to/vault/Projects" projects.epub --title "My Projects"
```
### Academic Paper Collection
```bash
obsipub "/path/to/research" research.epub \
--title "Research Collection" \
--author "Dr. Smith" \
--include-tags
```
### Clean Documentation Export
```bash
obsipub "/path/to/docs" documentation.epub \
--title "Project Documentation" \
--no-attachments
```
## Troubleshooting
### Common Issues
**"Command not found: pandoc"**
- Install Pandoc following the [installation guide](https://pandoc.org/installing.html)
**"Permission denied" errors**
- Ensure you have read access to the vault directory
- Check write permissions for the output directory
**Empty or missing content**
- Check `warning.log` for specific file processing issues
- Use `--verbose` flag for detailed logging
- Ensure markdown files have actual content after YAML processing
**Large file sizes**
- Use `--no-attachments` to exclude images and documents
- Consider converting subfolders instead of entire vault
### Getting Help
1. Check `warning.log` for detailed error information
2. Run with `--verbose` for debug output
3. Ensure all file paths are absolute or correctly relative
4. Verify Pandoc installation: `pandoc --version`
## Contributing
Contributions welcome! Please feel free to submit issues and pull requests.
### Development Setup
```bash
git clone https://github.com/yourusername/obsipub.git
cd obsipub
pip install -e ".[dev]"
```
## License
MIT License - see LICENSE file for details.
## Changelog
### v1.0.0
- Initial release
- Modular architecture
- CLI and Python API
- Bulletproof YAML processing
- Smart header hierarchy
- Attachment handling
- System file exclusion
Raw data
{
"_id": null,
"home_page": null,
"name": "obsipub",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "TCSenpai <tcsenpai@discus.sh>",
"keywords": "obsidian, epub, ebook, markdown, converter, knowledge-base",
"author": null,
"author_email": "TCSenpai <tcsenpai@discus.sh>",
"download_url": "https://files.pythonhosted.org/packages/86/ce/f12d05ecd82799747bb9d4612cb0474bbf5bf3211aa3beadc6fbfcddd48d/obsipub-1.0.1.tar.gz",
"platform": null,
"description": "# Obsipub\n\nConvert your Obsidian knowledge base to beautifully formatted EPUB ebooks with proper chapter structure and attachment handling.\n\n## Features\n\n\ud83d\udd27 **Smart Processing**\n- Bulletproof YAML front matter handling\n- Wikilink conversion to standard markdown links\n- Automatic attachment processing and inclusion\n- Hidden/system file exclusion (.git, .obsidian, etc.)\n\n\ud83d\udcda **Perfect EPUB Structure**\n- Folders become chapters with proper heading hierarchy\n- Notes become sections with shifted headers for clean TOC\n- Automatic table of contents generation\n- Proper metadata handling\n\n\ud83c\udfaf **Flexible Options**\n- Include or exclude attachments\n- Keep or remove Obsidian tags\n- Custom book title and author\n- Verbose logging for debugging\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\npip install obsipub\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/yourusername/obsipub.git\ncd obsipub\npip install -e .\n```\n\n## Requirements\n\n- Python 3.7+\n- [Pandoc](https://pandoc.org/installing.html) (for EPUB generation)\n\n### Installing Pandoc\n\n**Ubuntu/Debian:**\n```bash\nsudo apt install pandoc\n```\n\n**macOS:**\n```bash\nbrew install pandoc\n```\n\n**Windows:**\nDownload from [pandoc.org](https://pandoc.org/installing.html)\n\n## Quick Start\n\n### Command Line Usage\n\n```bash\n# Basic conversion\nobsipub /path/to/obsidian/vault output.epub\n\n# With custom title and author\nobsipub /path/to/vault mybook.epub --title \"My Knowledge Base\" --author \"Your Name\"\n\n# Exclude attachments and keep tags\nobsipub /path/to/vault book.epub --no-attachments --include-tags\n\n# Verbose output for debugging\nobsipub /path/to/vault book.epub --verbose\n```\n\n### Python API Usage\n\n```python\nfrom obsipub import ObsidianToEpubConverter\n\n# Basic usage\nconverter = ObsidianToEpubConverter(\n vault_path=\"/path/to/obsidian/vault\",\n output_epub_path=\"output.epub\",\n title=\"My Knowledge Base\",\n author=\"Your Name\"\n)\n\nsuccess = converter.convert()\nif success:\n print(\"Conversion completed!\")\nelse:\n print(\"Conversion failed - check warning.log\")\n\n# Advanced usage with options\nconverter = ObsidianToEpubConverter(\n vault_path=\"/path/to/vault\", \n output_epub_path=\"book.epub\",\n title=\"Advanced Guide\",\n author=\"Expert Author\",\n include_attachments=True, # Include images and files\n include_tags=False # Remove #tags from content\n)\n\nconverter.convert()\n```\n\n## How It Works\n\n### File Processing\n1. **Scanning**: Recursively scans your vault, ignoring system directories\n2. **Structure**: Maps folder hierarchy to EPUB chapter structure\n3. **Processing**: Handles YAML front matter, wikilinks, and attachments\n4. **Generation**: Uses Pandoc to create the final EPUB\n\n### Heading Hierarchy\n```\nFolder/ \u2192 # Chapter (H1)\n\u251c\u2500\u2500 Subfolder/ \u2192 ## Subchapter (H2) \n\u2502 \u251c\u2500\u2500 Note.md \u2192 ### Note Title (H3)\n\u2502 \u2502 \u251c\u2500\u2500 # Header \u2192 #### Header (H4)\n\u2502 \u2502 \u2514\u2500\u2500 ## Subheader \u2192 ##### Subheader (H5)\n```\n\n### What Gets Processed\n- \u2705 Markdown files (.md)\n- \u2705 Images (PNG, JPG, GIF, etc.)\n- \u2705 Documents (PDF, DOCX, etc.)\n- \u2705 Wikilinks `[[Note Name]]`\n- \u2705 Attachments `![[image.png]]`\n\n### What Gets Excluded\n- \u274c Hidden directories (`.obsidian`, `.git`, `.trash`)\n- \u274c System files (`.DS_Store`, `Thumbs.db`)\n- \u274c Temporary files (`.tmp`, `.log`, `.pyc`)\n\n## Command Line Options\n\n```bash\nobsipub [-h] [--title TITLE] [--author AUTHOR] [--no-attachments] \n [--include-tags] [--verbose] [--version] \n vault_path output_epub_path\n```\n\n### Arguments\n- `vault_path`: Path to your Obsidian vault directory\n- `output_epub_path`: Where to save the generated EPUB file\n\n### Options\n- `--title`: Custom book title (default: \"Obsidian Vault\")\n- `--author`: Book author name\n- `--no-attachments`: Skip including images and attachments\n- `--include-tags`: Keep Obsidian tags like `#important` in text\n- `--verbose`: Enable detailed logging output\n- `--version`: Show version information\n\n## Examples\n\n### Convert Specific Subfolder\n```bash\n# Convert only your \"Projects\" folder\nobsipub \"/path/to/vault/Projects\" projects.epub --title \"My Projects\"\n```\n\n### Academic Paper Collection\n```bash\nobsipub \"/path/to/research\" research.epub \\\n --title \"Research Collection\" \\\n --author \"Dr. Smith\" \\\n --include-tags\n```\n\n### Clean Documentation Export\n```bash\nobsipub \"/path/to/docs\" documentation.epub \\\n --title \"Project Documentation\" \\\n --no-attachments\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Command not found: pandoc\"**\n- Install Pandoc following the [installation guide](https://pandoc.org/installing.html)\n\n**\"Permission denied\" errors**\n- Ensure you have read access to the vault directory\n- Check write permissions for the output directory\n\n**Empty or missing content**\n- Check `warning.log` for specific file processing issues\n- Use `--verbose` flag for detailed logging\n- Ensure markdown files have actual content after YAML processing\n\n**Large file sizes**\n- Use `--no-attachments` to exclude images and documents\n- Consider converting subfolders instead of entire vault\n\n### Getting Help\n\n1. Check `warning.log` for detailed error information\n2. Run with `--verbose` for debug output\n3. Ensure all file paths are absolute or correctly relative\n4. Verify Pandoc installation: `pandoc --version`\n\n## Contributing\n\nContributions welcome! Please feel free to submit issues and pull requests.\n\n### Development Setup\n```bash\ngit clone https://github.com/yourusername/obsipub.git\ncd obsipub\npip install -e \".[dev]\"\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- Modular architecture\n- CLI and Python API\n- Bulletproof YAML processing\n- Smart header hierarchy\n- Attachment handling\n- System file exclusion\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 TCSenpai\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Convert Obsidian vaults to EPUB format with proper chapter structure",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://github.com/tcsenpai/obsipub#readme",
"Homepage": "https://github.com/tcsenpai/obsipub",
"Issues": "https://github.com/tcsenpai/obsipub/issues",
"Repository": "https://github.com/tcsenpai/obsipub.git"
},
"split_keywords": [
"obsidian",
" epub",
" ebook",
" markdown",
" converter",
" knowledge-base"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "25ac4672b6141766bfc01a951235c3afc7f849e7f1f4887ce9cc87c3e1b42f3e",
"md5": "86d222a059560c1cf1539b5fdd350d01",
"sha256": "a1529a8de42b7ef317e79d8aa235e4c2f0de9304b9cffc259442b019719be7bd"
},
"downloads": -1,
"filename": "obsipub-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86d222a059560c1cf1539b5fdd350d01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13842,
"upload_time": "2025-07-13T20:00:48",
"upload_time_iso_8601": "2025-07-13T20:00:48.300875Z",
"url": "https://files.pythonhosted.org/packages/25/ac/4672b6141766bfc01a951235c3afc7f849e7f1f4887ce9cc87c3e1b42f3e/obsipub-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "86cef12d05ecd82799747bb9d4612cb0474bbf5bf3211aa3beadc6fbfcddd48d",
"md5": "2e38247737fa806d21858d99520e2900",
"sha256": "f3b7ff12740382f4f0fe1a52f4501b344248160f5b3c67f2fd717cbf784ee83e"
},
"downloads": -1,
"filename": "obsipub-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "2e38247737fa806d21858d99520e2900",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15299,
"upload_time": "2025-07-13T20:00:49",
"upload_time_iso_8601": "2025-07-13T20:00:49.694216Z",
"url": "https://files.pythonhosted.org/packages/86/ce/f12d05ecd82799747bb9d4612cb0474bbf5bf3211aa3beadc6fbfcddd48d/obsipub-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 20:00:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tcsenpai",
"github_project": "obsipub#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "PyYAML",
"specs": [
[
">=",
"5.4.0"
]
]
}
],
"lcname": "obsipub"
}
