| Name | notion2hugo JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | |
| Summary | Converts Notion documents into Markdown format files compatbile with the Hugo framework. |
| upload_time | 2023-08-16 19:42:32 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | <4,>=3.9 |
| license | MIT License Copyright (c) 2023 Chintak Sheth 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 |
notion
hugo
markdown
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Notion2Hugo
<!-- markdownlint-disable -->
<div align="center">
<p>
<a href="https://pypi.org/project/notion2hugo/"><img alt="PyPI" src="https://img.shields.io/pypi/v/notion2hugo?style=for-the-badge&color=blue"></a>
<a href="LICENSE"><img alt="GitHub" src="https://img.shields.io/github/license/chintak/notion2hugo?style=for-the-badge"></a>
<img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/notion2hugo?style=for-the-badge&color=blue">
</p>
</div>
<!-- markdownlint-enable -->
Export content written in Notion to markdown, compatible for [Hugo](https://gohugo.io/) blog.
You can use Notion as a CMS in order to author, edit, and manage all your content while leverage the power of Hugo in order to serve the content statically on your blog site. This lets you leverage the best of both worlds - powerful and expressive UX of Notion for authoring along with speed and pre-built feature rich themes for personal blog site.
The package ships with a script in order to export content from Notion in a compatible format.
```shell
$ pip3 install notion2hugo
$ publish_notion_to_hugo [-h] config_path
```
## Demo
[Demo Notion Page](https://chintaksheth.notion.site/TEMPLATE-Markdown-Syntax-with-Notion-Hugo-cce2284449bf4a97a5222a150017db66) --> [Hugo Markdown Output](https://gist.github.com/chintak/ae65c187c962b9c0b9b4df7de9df22bc)
Feel free to use the [Demo Notion Page](https://chintaksheth.notion.site/TEMPLATE-Markdown-Syntax-with-Notion-Hugo-cce2284449bf4a97a5222a150017db66) as a template for setting up your blogging Notion database.
## Getting Started
Install the package using Pip:
```shell
$ pip3 install notion2hugo
```
Follow the steps below to get started:
1. Follow the Notion developer guide in order to [setup an Access Token and an Integration](https://developers.notion.com/docs/authorization) with at least "Read" access to the relevant database.
2. Expose the access token and the database ID as environment variables in your shell.
```
export NOTION_TOKEN='<your-access-token-here>'
export NOTION_DATABASE_ID='<database-id-with-read-integration-setup>'
```
3. Clone the `src/notion2hugo/config.sample.toml` file as `config.toml` and add in your custom settings. You can leverage the properties in your Notion database in order to determine the name of the published post.
4. Run the script mentioned above and profit!
```bash
$ publish_notion_to_hugo /path/to/config.toml
```
### Note about output structure
Currently, the output markdown generated has the following directory structure:
- {parent_dir}/ (_provided in the config, cleared at the start of execution_)
- {post1_name}/ (_provided in the config or defaults to the "Title" property auto populated for all posts_)
- images/ (_contains all the image assets used in the post_)
- index.md (_contains the exported post markdown content with an appropriately formatter front matter_)
- {post2_name}/
- images/
- index.md
- ...
### Note about `index.md` front matter
We export all the properties specified in the Notion database for the page to the front matter in the format shown below:
```
---
prop1: prop1_value
prop2: prop2_value
...
Title: 'Post title"
---
```
This is intended to mimic the front matter [format as shown here](https://gohugo.io/getting-started/quick-start/#add-content). The full list of supported front matter variables is provided here - [front matter variables](https://gohugo.io/content-management/front-matter/#front-matter-variables).
The Notion database can be setup in order to have properties as supported by Hugo in order to easily export them and make the best use of the options available. For ex, you could have a property as:
- `"Draft"` with a value of `"false"` or `"true"` and Hugo will correctly handle them as a draft post or a published post.-
- `Date` property can be used to specify the post publish date.
- `Tags`, `Series`...
- On the flip side, if you'd like to have other arbitrary properties in your Notion database, you should prepend them with a `#` (eg, `# Arbitrary Prop`), so that they don't interfere with Hugo front matter format and don't result in an error.
## Configuration
Here is the [`config.sample.toml`](https://github.com/chintak/notion2hugo/blob/master/src/notion2hugo/config.sample.toml):
```toml
#
# Copy this file to config.toml and update the field below
#
[provider_config]
## override the id here or defaults to NOTION_DATABASE_ID env
# database_id = "<notion_database_id>"
## specify filter here, refer to Notion API Dev resources for format
# filter = {property = "# Status", status = {equals = "Outline"}}
# filter = {property = "# Status", status = {does_not_equal = "Not Started"}}
[formatter_config]
[exporter_config]
parent_dir = "/tmp/notion2hugo_output_dir"
## specify page prop from Notion here or
## remove it in order use page id as dir
post_name_property_key = "Title" # 'Title' prop is added by default.
[runner_config]
exporter_config_cls = "notion2hugo.exporter.MarkdownExporterConfig"
formatter_config_cls = "notion2hugo.formatter.HugoFormatterConfig"
provider_config_cls = "notion2hugo.provider.NotionProviderConfig"
```
## Supported Features
Exporting markdown for the following Notion features is supported:
- [X] Heading 1/2/3/Paragraphs
- [X] Text annotations - bold, italics, underline, etc.
- [X] Table (with markdown in cells)
- [X] Images (with captions)
- [X] Code (inline and block)
- [X] [Mermaid diagrams](https://mermaid.js.org/)
- [X] Blockquote
- [X] Math equations (both inline and block)
- [X] Text Highlight
## Roadmap for future developement
Currently, the following Notion features are not supported for export and will be supported in future versions:
- [X] Checklist or TODOs
- [ ] Callouts
- [ ] Cross referencing pages in the database, that is, we'd like to update the URL appropriately to refer to the published post on the blog rather than to the notion page.
- [ ] Gist, twitter or other embeds.
## Contributions
Contributions are more than welcome! Please feel free to open an issue or a pull request for any bugs/feature request or any other improvements. Cheers!
Raw data
{
"_id": null,
"home_page": "",
"name": "notion2hugo",
"maintainer": "",
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": "",
"keywords": "notion,hugo,markdown",
"author": "",
"author_email": "Chintak Sheth <chintaksheth@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/81/2b/779fc2d85ee18839635106b9915b0bd61f0303b6a5acac4e910dd8cedda8/notion2hugo-0.2.0.tar.gz",
"platform": null,
"description": "# Notion2Hugo\n\n<!-- markdownlint-disable -->\n<div align=\"center\">\n <p>\n <a href=\"https://pypi.org/project/notion2hugo/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/notion2hugo?style=for-the-badge&color=blue\"></a>\n <a href=\"LICENSE\"><img alt=\"GitHub\" src=\"https://img.shields.io/github/license/chintak/notion2hugo?style=for-the-badge\"></a>\n <img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/notion2hugo?style=for-the-badge&color=blue\">\n </p>\n</div>\n<!-- markdownlint-enable -->\n\nExport content written in Notion to markdown, compatible for [Hugo](https://gohugo.io/) blog.\n\nYou can use Notion as a CMS in order to author, edit, and manage all your content while leverage the power of Hugo in order to serve the content statically on your blog site. This lets you leverage the best of both worlds - powerful and expressive UX of Notion for authoring along with speed and pre-built feature rich themes for personal blog site.\n\nThe package ships with a script in order to export content from Notion in a compatible format.\n\n```shell\n$ pip3 install notion2hugo\n$ publish_notion_to_hugo [-h] config_path\n```\n\n## Demo\n\n[Demo Notion Page](https://chintaksheth.notion.site/TEMPLATE-Markdown-Syntax-with-Notion-Hugo-cce2284449bf4a97a5222a150017db66) --> [Hugo Markdown Output](https://gist.github.com/chintak/ae65c187c962b9c0b9b4df7de9df22bc)\n\nFeel free to use the [Demo Notion Page](https://chintaksheth.notion.site/TEMPLATE-Markdown-Syntax-with-Notion-Hugo-cce2284449bf4a97a5222a150017db66) as a template for setting up your blogging Notion database.\n\n## Getting Started\n\nInstall the package using Pip:\n```shell\n$ pip3 install notion2hugo\n```\n\nFollow the steps below to get started:\n1. Follow the Notion developer guide in order to [setup an Access Token and an Integration](https://developers.notion.com/docs/authorization) with at least \"Read\" access to the relevant database.\n2. Expose the access token and the database ID as environment variables in your shell.\n ```\n export NOTION_TOKEN='<your-access-token-here>'\n export NOTION_DATABASE_ID='<database-id-with-read-integration-setup>'\n ```\n3. Clone the `src/notion2hugo/config.sample.toml` file as `config.toml` and add in your custom settings. You can leverage the properties in your Notion database in order to determine the name of the published post.\n4. Run the script mentioned above and profit!\n ```bash\n $ publish_notion_to_hugo /path/to/config.toml\n ```\n\n### Note about output structure\n\nCurrently, the output markdown generated has the following directory structure:\n- {parent_dir}/ (_provided in the config, cleared at the start of execution_)\n - {post1_name}/ (_provided in the config or defaults to the \"Title\" property auto populated for all posts_)\n - images/ (_contains all the image assets used in the post_)\n - index.md (_contains the exported post markdown content with an appropriately formatter front matter_)\n - {post2_name}/\n - images/\n - index.md\n - ...\n\n### Note about `index.md` front matter\n\nWe export all the properties specified in the Notion database for the page to the front matter in the format shown below:\n```\n---\nprop1: prop1_value\nprop2: prop2_value\n...\nTitle: 'Post title\"\n---\n```\n\nThis is intended to mimic the front matter [format as shown here](https://gohugo.io/getting-started/quick-start/#add-content). The full list of supported front matter variables is provided here - [front matter variables](https://gohugo.io/content-management/front-matter/#front-matter-variables).\n\nThe Notion database can be setup in order to have properties as supported by Hugo in order to easily export them and make the best use of the options available. For ex, you could have a property as:\n- `\"Draft\"` with a value of `\"false\"` or `\"true\"` and Hugo will correctly handle them as a draft post or a published post.-\n- `Date` property can be used to specify the post publish date.\n- `Tags`, `Series`...\n- On the flip side, if you'd like to have other arbitrary properties in your Notion database, you should prepend them with a `#` (eg, `# Arbitrary Prop`), so that they don't interfere with Hugo front matter format and don't result in an error.\n\n## Configuration\n\nHere is the [`config.sample.toml`](https://github.com/chintak/notion2hugo/blob/master/src/notion2hugo/config.sample.toml):\n\n```toml\n#\n# Copy this file to config.toml and update the field below\n#\n\n[provider_config]\n## override the id here or defaults to NOTION_DATABASE_ID env\n# database_id = \"<notion_database_id>\"\n## specify filter here, refer to Notion API Dev resources for format\n# filter = {property = \"# Status\", status = {equals = \"Outline\"}}\n# filter = {property = \"# Status\", status = {does_not_equal = \"Not Started\"}}\n\n[formatter_config]\n\n[exporter_config]\nparent_dir = \"/tmp/notion2hugo_output_dir\"\n## specify page prop from Notion here or\n## remove it in order use page id as dir\npost_name_property_key = \"Title\" # 'Title' prop is added by default.\n\n[runner_config]\nexporter_config_cls = \"notion2hugo.exporter.MarkdownExporterConfig\"\nformatter_config_cls = \"notion2hugo.formatter.HugoFormatterConfig\"\nprovider_config_cls = \"notion2hugo.provider.NotionProviderConfig\"\n```\n\n## Supported Features\n\nExporting markdown for the following Notion features is supported:\n- [X] Heading 1/2/3/Paragraphs\n- [X] Text annotations - bold, italics, underline, etc.\n- [X] Table (with markdown in cells)\n- [X] Images (with captions)\n- [X] Code (inline and block)\n- [X] [Mermaid diagrams](https://mermaid.js.org/)\n- [X] Blockquote\n- [X] Math equations (both inline and block)\n- [X] Text Highlight\n\n## Roadmap for future developement\n\nCurrently, the following Notion features are not supported for export and will be supported in future versions:\n\n- [X] Checklist or TODOs\n- [ ] Callouts\n- [ ] Cross referencing pages in the database, that is, we'd like to update the URL appropriately to refer to the published post on the blog rather than to the notion page.\n- [ ] Gist, twitter or other embeds.\n\n## Contributions\n\nContributions are more than welcome! Please feel free to open an issue or a pull request for any bugs/feature request or any other improvements. Cheers!\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Chintak Sheth 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. ",
"summary": "Converts Notion documents into Markdown format files compatbile with the Hugo framework.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/chintak/notion2hugo"
},
"split_keywords": [
"notion",
"hugo",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "660eefa0c0bb064db7ca5753bc881f67123aed9d3a958e865c5ffe23824d88f8",
"md5": "c2e2216a817a9686e3dac8f97beab49f",
"sha256": "4a5bde4992ecafdcbee115058b34306679e40b6aa514810b135c89f31542e804"
},
"downloads": -1,
"filename": "notion2hugo-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2e2216a817a9686e3dac8f97beab49f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 16534,
"upload_time": "2023-08-16T19:42:31",
"upload_time_iso_8601": "2023-08-16T19:42:31.212411Z",
"url": "https://files.pythonhosted.org/packages/66/0e/efa0c0bb064db7ca5753bc881f67123aed9d3a958e865c5ffe23824d88f8/notion2hugo-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "812b779fc2d85ee18839635106b9915b0bd61f0303b6a5acac4e910dd8cedda8",
"md5": "afe04ff457f3a56b033682781c111cde",
"sha256": "8c91a0ee0aa1f65e520e529cc83c19f767e0ce665520d7125219b173d8376654"
},
"downloads": -1,
"filename": "notion2hugo-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "afe04ff457f3a56b033682781c111cde",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 17149,
"upload_time": "2023-08-16T19:42:32",
"upload_time_iso_8601": "2023-08-16T19:42:32.327473Z",
"url": "https://files.pythonhosted.org/packages/81/2b/779fc2d85ee18839635106b9915b0bd61f0303b6a5acac4e910dd8cedda8/notion2hugo-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-16 19:42:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chintak",
"github_project": "notion2hugo",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "notion2hugo"
}
