Write and publish without GitHub
Write your docs in Syntext or upload the Markdown you have, publish when you're ready, restore any earlier version, and move to GitHub and back.
Your docs don't need a repository. A project written in Syntext keeps its pages in Syntext: you write them in the web editor, every save is kept as a revision, and the site changes when you publish. You can move the project to a GitHub repository later — and back again — without losing a page.
| Written in Syntext | GitHub | |
|---|---|---|
| Pages live in | Syntext | Your repository |
| A save is | A draft, until you publish | A commit, which builds the site |
| History | History in the editor, with restore | Your repository's commits |
| Start from | A template, or an upload | A repository |
Start a project
Go to app.syntext.dev/projects → New project.
{subdomain}-docs.syntext.dev) and who can read the docs. Nothing is created yet.Where your docs live — choose one:
Skip for now creates the project with no pages. Open the editor to add the first one, or connect GitHub later.
Write in Syntext
Pick a template under Start from, then Create and publish. Syntext creates the project with the template's pages and publishes them, so the site is live straight away: Your site is live at …. Choose Open the editor to make it yours.
| Template | For | Starts on the preset |
|---|---|---|
| Help centre | Answers for customers, by topic | Paper |
| Product guides | How-tos and walkthroughs | Orbit |
| Handbook | Policies and processes for your team | Margin |
| Developer docs | Guides beside an API reference | Workbench |
| Blank | A home page and a short guide to writing, organising and publishing | Plain |
Each template is a home page, a handful of pages and a syntext.json, all yours to change. Switch preset any time in Settings › Appearance.
If the month's builds are used up, the project is still created with its pages, and the site goes live when you publish after your plan renews or after upgrading.
Upload Markdown
Choose Upload files, then drop a .zip or a folder on the box — or use Choose a .zip or Choose a folder — and select Upload and publish. Syntext imports the pages, images and config as one revision and publishes them.
What you can upload: Markdown and MDX pages, images, and syntext.json or a Mintlify mint.json / docs.json.
.md and .mdx files, up to 1 MB each.syntext.json is used as it is. With none, a Mintlify mint.json or docs.json is converted to syntext.json (Config imported). With neither, the sidebar lists your pages by folder (No config: sidebar by folder).The upload is laid out the way the CLI reads a project: a single folder wrapping everything is removed, pages in docs/ move to the top level, and images in public/ are served from their path (public/images/logo.png is /images/logo.png).
Anything else — hidden files, __MACOSX, node_modules, PDFs, videos, files with names that aren't allowed — is skipped, and the result lists each skipped file with the reason.
Limits
| Limit | Value |
|---|---|
| Upload | 50 MB |
| Unpacked | 100 MB |
| An image | 5 MB |
| An SVG | 512 KB |
| Files in a project | 2,000 |
| Size of a project | 200 MB |
| Uploads | 30 an hour per workspace, one at a time per project |
If an upload is refused
Nothing is imported when an upload is refused. The box says why:
| Message | What to do |
|---|---|
| The upload is too large | Leave out videos and build output, or upload in parts |
| That file isn't a ZIP we can read | Zip the folder again (right-click › Compress) and upload the new file |
| The archive was refused | A file in it expands far more than a document would. Zip the folder again from the original files |
| The archive contains a link | Replace the symbolic link with the file it points to, and zip again |
| The archive is password-protected | Zip the folder again without a password |
| This kind of ZIP isn't supported | Zip the folder again with your system's built-in compression |
| No pages found | The upload has no .md or .mdx files. Pick the folder that holds your Markdown pages |
| Another upload is still running | Wait for the upload into this project to finish, then try again |
| Too many uploads | Each workspace can upload 30 times an hour. Wait a while and try again |
| The project would be too large | A project written in Syntext holds up to 200 MB of files. Leave out large images or videos |
| Too many files | A project written in Syntext holds up to 2,000 files. Upload only the docs folder |
| A file name isn't allowed | Rename files whose names start with a dot or contain unusual characters |
| This project publishes from GitHub | Commit the files to its repository instead, or disconnect GitHub first |
When the month's builds are used up, the upload is still imported: Imported, but not published yet. Publish from the editor when you're ready.
To upload from a script, use Import Content. It also takes mode=merge, which adds and overwrites files without deleting the rest.
Drafts and publishing
In a project written in Syntext, the editor's Save draft (⌘S / Ctrl+S) keeps your changes without changing the live site: Saved as draft. Creating or deleting a page is a draft too.
The toolbar counts what the site doesn't show yet — 3 changes not published — next to Publish. Select Publish to build and deploy the latest save; the button shows the build until it's live, then Published. If the build fails, the site stays as it was and your drafts are kept.
Each publish is a build. When the month's builds are used up, You've used this month's publishes explains your options — upgrade, or publish again when your plan renews. Your changes stay saved as a draft; nothing is lost.
History and restore
Every save, upload and restore is a revision. Open History in the editor to see them, newest first, with who made each one, what made it (Editor, Upload, Template, Restore, Assistant, MCP, API) and whether it's Published or still a Draft. Switch between This page and All pages.
Select a revision to see the files it changed, each with a diff against what it was just before. Then:
Syntext asks you to confirm first. A restore is saved as a new revision, so history is never rewritten and a restore can be undone by restoring again. It waits as a draft until you publish — or tick Publish right away.
Move to GitHub
You can move a project written in Syntext to a GitHub repository whenever you like. Go to Settings › Repository. Under Content source, the project shows Written in Syntext, the latest revision and whether every change is published. Choose Connect GitHub.
docs/ or the folder the repository already uses; / is the root.Choose what to keep. You get two choices, depending on what the folder holds:
| Choice | Offered when | What happens |
|---|---|---|
| Push my pages to the repo | The folder is empty | One commit adds your Syntext pages to the branch. From then on, pushes publish the site |
| Open a pull request | The folder is empty | Review the pages in a pull request first. The site keeps publishing from Syntext until it's merged |
| Use the repo's pages | The folder has docs | Nothing is written. The site publishes from the repository; your Syntext pages are kept in history |
| Replace them with my Syntext pages (opens a pull request) | The folder has docs | Your pages go into a pull request. The site keeps publishing from Syntext until it's merged |
A choice the repository can't take stays listed but disabled, with the reason — for example, pages can only go into docs/ or the root, since builds read pages from one of those.
Pages go under the docs folder, images under public/, and syntext.json at the root of the repository, with your brand settings in it.
While the pull request is open
Content source shows Waiting for pull request #N. Until it's merged, nothing changes: the editor keeps saving drafts to Syntext and the site keeps publishing from Syntext. Use Open pull request to review it on GitHub.
If a move doesn't finish — GitHub was unreachable or asked Syntext to slow down — GitHub wasn't connected says why, with Try again. Files already sent aren't sent again.
Back to Syntext
A GitHub project shows Pages come from owner/repo. Pushes publish the site. Choose Disconnect GitHub to write it in Syntext again.
Syntext copies the repository's current pages, config and images into Syntext as a new revision, so you carry on editing in the browser from where the repository left off: Disconnected. N pages copied into Syntext as revision R. Your live site is unchanged. The site keeps its current deploy until you next publish, and the repository isn't touched.
Do it with the API
| Task | Endpoint |
|---|---|
| Create from a template | Create Project with template — see List Templates |
| Save drafts | Save Pages, with publish: true to publish too |
| Upload | Import Content |
| Publish | Publish Content |
| History and restore | Content History, Restore Revision |
| Move to GitHub | Preview GitHub Link, Connect GitHub |
| Back to Syntext | Disconnect GitHub |
The hosted MCP connector's write tools work on projects written in Syntext too. With mode: "draft" an AI assistant saves an unpublished revision, just like Save draft; its drafts and yours are one change, "draft", that it can diff, send for review, publish or discard — see Draft, review and publish.