notion_publish 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a9b4306daec96d259c074e2386d006468f5adc2500764b8559b1b65c169e1ba
+  data.tar.gz: 7015f9427836474584cb1665f81d509bda08e74329b653eda7b5692ce1daa740
+SHA512:
+  metadata.gz: c78e9ab6ef5ad4c8e428208bf878c0c89fffd8fdbfdd896e326a7e640e31713c8beab0ad2683677a04b03e0f5db87052bd09dd66ddb525fc65a77e800abe009e
+  data.tar.gz: ee0afe9af082ac9dbc238146b2f8d12037d9b3f1ce6d247e1552a1ecc130d8b18e713d2374f1ca4050b3edc41bf5b0bf5a97cf24523a9e7b115ca61998f1c7f3

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-26
+
+First public release.
+
+### Added
+
+- Publish a Markdown file to a Notion page, database, or data source, named by ID, URL, or exact
+  database name. Notion does the Markdown conversion.
+- Update the same page in place on later runs. `notion-publish-manifest.yml`, which you commit,
+  records which page each file became, so a tracked file needs no destination.
+- `republish [DIR]` updates every page the manifest tracks, from each file's front matter plus the
+  `--title` and `--keep-h1` it was last published with. Properties set with flags are left alone.
+- Set database properties from front matter, `--properties-json`, or `--property`, validated
+  against the live schema before anything is written. Properties the tool set before and no longer
+  sets are cleared; properties it never set are left alone.
+- Detect edits made in Notion since the last publish, and pages moved to Notion's trash. An edited
+  page stops the publish with exit code 3 unless `--force` is given; a trashed page is published
+  afresh.
+- Upload local images, including images under list items, and place them as image blocks.
+- Join hard-wrapped lines before sending, since Notion makes a block of each line.
+- Rewrite links between published documents to their Notion URLs, with `relink` for a second pass.
+- Page icon and cover from an emoji, URL, or local file.
+- `status`, `relink`, `adopt`, and `properties` subcommands.
+- Check three pages at a time in `republish`, `status`, and `relink`; `-j`/`--jobs` changes the
+  number. A progress line appears when stderr is a terminal.
+- Output lists only files where something happened. `-v` lists every file, `-vv` logs each API
+  request, and `-vvv` adds shortened bodies. The token is never logged.
+- `--dry-run` and `--json` output for scripts and CI.
+
+[0.1.0]: https://github.com/outsidecto/notion-publish/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Outside CTO
+
+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.

data/README.md

@@ -0,0 +1,221 @@
+# notion-publish
+
+[![CI](https://github.com/outsidecto/notion-publish/actions/workflows/ci.yml/badge.svg)](https://github.com/outsidecto/notion-publish/actions/workflows/ci.yml)
+
+Keep Notion pages in step with Markdown files in a Git repository.
+
+Many teams write their documents in Git, where changes are reviewed and every version is kept. The
+people who read those documents often work in Notion. `notion-publish` publishes each Markdown file
+as a Notion page, and later runs update the same page in place. Git stays the source of truth, and
+Notion shows a current copy.
+
+```console
+$ notion-publish policies/access-control.md --parent Policies --link
+Published policies/access-control.md to database "Policies" (2efab123-...)
+  https://app.notion.com/p/Access-Control-Policy-3cfab123cd45818b9a72c2bd16e85a62
+
+$ notion-publish policies/access-control.md
+Unchanged policies/access-control.md
+```
+
+## What it does
+
+- **Updates pages in place.** A committed file, `notion-publish-manifest.yml`, records which page
+  each file became. Republishing replaces the page body and keeps its URL, so links to it keep
+  working.
+- **Republishes everything it tracks** with one command, `notion-publish republish`, using what it
+  recorded about each file.
+- **Protects edits made in Notion.** If someone edited the page in Notion since the last publish,
+  the tool stops and exits with code 3 rather than overwriting their work.
+- **Sets database properties** from front matter or flags. Values are checked against the database
+  schema before anything is written, so a typo in a select option fails instead of creating a new
+  option.
+- **Rewrites links between documents** to their Notion URLs.
+- **Uploads local images** and places them in the page.
+- **Fixes wrapped text.** Notion treats each line of a hard-wrapped paragraph as its own block. The
+  tool joins the lines first.
+- **Reports drift.** `notion-publish status` lists files changed locally, pages changed in Notion
+  or moved to Notion's trash, and files that were never published.
+
+Notion does the Markdown conversion itself, through its
+[Markdown API](https://developers.notion.com/). The gem has no runtime dependencies beyond the Ruby
+standard library.
+
+## Install
+
+Requires Ruby 3.2 or later.
+
+    gem install notion_publish
+
+Or add it to a Gemfile:
+
+```ruby
+gem "notion_publish", require: false
+```
+
+## Quick start
+
+1. **Create a connection.** Go to
+   [notion.so/profile/integrations](https://www.notion.so/profile/integrations), create an internal
+   connection, and give it the Read, Update, and Insert content capabilities. Copy the token.
+
+2. **Share a destination with it.** In Notion, open the page or database you will publish into,
+   choose **••• → Connections**, and add your connection.
+
+3. **Set the token.**
+
+       export NOTION_API_TOKEN=ntn_...
+       notion-publish --whoami
+
+4. **Publish.** `--parent` takes a page or database ID, a Notion URL, or the exact name of a
+   database.
+
+       notion-publish docs/onboarding.md --link \
+         --parent 'https://app.notion.com/p/Team-Docs-2efab123...'
+
+   `--link` creates `notion-publish-manifest.yml` at the repository root. Commit it. Without it,
+   the next run cannot find the page and will create a second copy.
+
+5. **Edit the file and publish again.** The page is updated in place.
+
+## Keeping a repository in sync
+
+Put the destination in a settings file, so it does not have to be typed each time. Settings apply
+to the directory they are in and everything below it.
+
+```yaml
+# policies/.notion-publish.yml
+database: Policies
+icon: 📘
+```
+
+Set database properties in each file's front matter:
+
+```markdown
+---
+properties:
+  Owner: Jane Doe
+  Status: Approved
+  Review Date: 2027-01-15
+---
+# Access Control Policy
+...
+```
+
+The first time, publish the directory with a loop. Then run `relink` to fix links to documents
+that were published later in the loop:
+
+```sh
+for f in policies/*.md; do
+  notion-publish "$f" --link
+done
+notion-publish relink
+```
+
+After that, one command updates every page the manifest tracks:
+
+```console
+$ notion-publish republish
+Updated policies/incident-response.md to database "Policies" (2efab123-...)
+  https://app.notion.com/p/Incident-Response-Policy-...
+12 documents: 11 unchanged, 1 updated
+```
+
+Only files where something happened are listed. `-v` lists every file. In a terminal, a progress
+line shows which file is being checked while it runs.
+
+`republish` needs no file names and no destination. Each page is updated where it already is, from
+the file's current front matter plus any `--title` or `--keep-h1` it was last published with.
+Properties that were set with `--property` are left as they are. A new file is not picked up until
+you publish it once by name.
+
+Check where things stand at any time:
+
+```console
+$ notion-publish status
+/repo/notion-publish-manifest.yml -- 12 tracked
+
+Changed locally (1)
+  policies/access-control.md
+
+Changed in Notion (1)
+  policies/incident-response.md
+    https://app.notion.com/p/...
+
+10 in sync, 1 changed locally, 1 changed in Notion
+```
+
+`status -v` also lists the documents that are in sync.
+
+### Publishing from GitHub Actions
+
+This workflow republishes on every push to `main` and commits the updated manifest back.
+Store the token as a repository secret named `NOTION_API_TOKEN`.
+
+```yaml
+name: Publish to Notion
+
+on:
+  push:
+    branches: [main]
+    paths: ["policies/**.md"]
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - run: gem install notion_publish
+      - name: Republish
+        env:
+          NOTION_API_TOKEN: ${{ secrets.NOTION_API_TOKEN }}
+        run: notion-publish republish
+      - name: Commit notion-publish-manifest.yml
+        if: success() || failure()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add notion-publish-manifest.yml
+          if ! git diff --cached --quiet; then
+            git commit -m "Record published Notion pages"
+            git push
+          fi
+```
+
+If a page was edited in Notion, `republish` leaves it alone and exits with code 3, which fails the
+job. The other files still publish. Look at the page, move the change into the Markdown, and publish
+that file with `--force`.
+
+## Documentation
+
+[docs/usage.md](docs/usage.md) is the full reference. It covers destinations, settings, every
+property type, the manifest, adopting pages that already exist, images, exit codes, and JSON
+output.
+
+## Known limits
+
+- A new file must be published once by name before `republish` includes it.
+- Images inside a paragraph cannot be placed, since Notion has no inline images.
+- Files over 20 MB are not uploaded, because Notion's multi-part upload is not implemented.
+- H5 and H6 become heading 4 in Notion.
+
+## Development
+
+    bundle install
+    bundle exec rake     # tests and RuboCop
+
+Tests use Minitest and WebMock and make no network calls. Bug reports and pull requests are welcome
+at [github.com/outsidecto/notion-publish](https://github.com/outsidecto/notion-publish). To report a
+security problem, see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+This project is not affiliated with or endorsed by Notion Labs, Inc.

data/docs/notion-publish-home-page.md

@@ -0,0 +1,105 @@
+# notion_publish
+
+Many teams keep their important documents in Git, where changes get reviewed and every version is
+kept. The people who read those documents often work in Notion instead. So somebody copies each
+document over by hand, the two copies drift apart, and after a few months nobody can say which one
+is current.
+
+`notion_publish` is a command-line tool that publishes Markdown files from a Git repository into
+Notion and then keeps those pages up to date. Git stays the authoritative copy. Notion shows a
+current version of it.
+
+It was built for a security and compliance corpus, where an auditor can reasonably ask which Notion
+page corresponds to a given policy, and where "somebody pasted it in last spring" is not a good
+answer.
+
+## What it looks like
+
+Publish a file. `--parent` takes a page ID, a Notion URL, or the exact name of a database:
+
+    $ notion-publish policies/access-control.md --parent 'Policies' --link
+    Published policies/access-control.md to database "Policies" (2efab123-...)
+      https://app.notion.com/p/Access-Control-Policy-3cfab123cd45818b9a72c2bd16e85a62
+
+`--link` writes a file called `notion-publish-manifest.yml`, which records the page each document
+became. You commit that file. From then on, one command brings every page up to date:
+
+    $ notion-publish republish
+    Updated policies/incident-response.md to database "Policies" (2efab123-...)
+      https://app.notion.com/p/Incident-Response-Policy-...
+    12 documents: 11 unchanged, 1 updated
+
+Before publishing anything, you can ask what has moved apart:
+
+    $ notion-publish status
+    /repo/notion-publish-manifest.yml -- 12 tracked
+
+    Changed locally (1)
+      policies/access-control.md
+
+    Changed in Notion (1)
+      policies/incident-response.md
+        https://app.notion.com/p/...
+
+    10 in sync, 1 changed locally, 1 changed in Notion
+
+`status` exits with code 3 when something needs a person to look at it, so it also works as a check
+in continuous integration.
+
+## The parts that are easy to get wrong
+
+- **Updating instead of duplicating.** Because the manifest records which page each file became,
+  publishing again replaces that page's contents and keeps its URL. Links people have already
+  shared keep working.
+- **Edits made in Notion.** The tool records what Notion returned after each publish and reads the
+  page again before the next one. If somebody edited the page, it stops and says so rather than
+  overwriting their work.
+- **Pages deleted in Notion.** Deleting a page in Notion moves it to the trash, where the API still
+  returns it with all its content. The tool notices the difference and publishes a fresh page.
+- **Database properties.** Values are checked against the live database schema before anything is
+  written, so a misspelled select option is an error instead of a brand-new option added to your
+  schema. Properties the tool set before and no longer sets are cleared; properties it never set are
+  left alone.
+- **Links between documents.** A relative link to another Markdown file does not merely break in
+  Notion. Notion turns it into a link to a domain nobody owns. Links to published documents are
+  rewritten to their Notion URLs.
+- **Local images.** Notion's Markdown import only understands images at public URLs, and a local
+  path produces an empty image block with no error at all. Local images are uploaded and placed as
+  real image blocks.
+- **Hard-wrapped text.** Notion makes a separate block out of each line, so a file wrapped at a
+  column width arrives looking double-spaced. Wrapped paragraphs and list items are joined back
+  together first.
+
+## Why another gem
+
+Notion does not publish an official Ruby SDK. The client it maintains is for JavaScript.
+
+Ruby has a dozen unofficial Notion gems, and they address two different problems. Most are API
+clients that wrap the HTTP endpoints, and the widely used ones have not seen a release in some time:
+`notion-ruby-client` last shipped in October 2023, `notion-sdk-ruby` in June 2022, and `notion` in
+January 2021. Notion reorganized its data model in September 2025, when a database became a
+container holding one or more data sources, and the schema and rows moved to the data source. A
+client written before that models an API that no longer works the same way.
+
+The gems that do handle Markdown run in the other direction. `notion_to_md` exports pages from
+Notion into Markdown, and `notion_rails` renders Notion blocks as HTML inside a Rails application.
+Both are useful. Neither publishes into Notion, and neither keeps a record of what was published,
+which is the part that makes a second run safe instead of duplicating everything.
+
+The conversion works differently here as well. Tools in this area usually build Notion's block JSON
+themselves, which means carrying a Markdown parser and keeping it in step with Notion's block types.
+`notion_publish` sends the Markdown and lets Notion parse it, using the Markdown parameter Notion's
+own API accepts. Tables, nested lists, task lists, and fenced code arrive correctly because Notion
+did that work. It is also why the gem has no runtime dependencies at all: the client is `Net::HTTP`
+from the Ruby standard library.
+
+## Getting it
+
+Requires Ruby 3.2 or later.
+
+    gem install notion_publish
+
+The source code, the full usage reference, and the issue tracker are on GitHub:
+[github.com/outsidecto/notion-publish](https://github.com/outsidecto/notion-publish).
+
+MIT licensed. This project is not affiliated with or endorsed by Notion Labs, Inc.