/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Write and publish without GitHub

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.

9 min read

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 SyntextGitHub
Pages live inSyntextYour repository
A save isA draft, until you publishA commit, which builds the site
HistoryHistory in the editor, with restoreYour repository's commits
Start fromA template, or an uploadA repository

Start a project

Go to app.syntext.dev/projects → New project.

1.
Name your project — the name, the subdomain ({subdomain}-docs.syntext.dev) and who can read the docs. Nothing is created yet.
2.

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 — start from a template and write in the browser. No repository needed.
◦
Upload files — bring Markdown or MDX files you already have, as a .zip or a folder.
◦
Import from a URL — coming soon.
◦
Connect GitHub — publish from a repository on every push. See Getting started.
3.
Publish — the first build runs while you watch.

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.

TemplateForStarts on the preset
Help centreAnswers for customers, by topicPaper
Product guidesHow-tos and walkthroughsOrbit
HandbookPolicies and processes for your teamMargin
Developer docsGuides beside an API referenceWorkbench
BlankA home page and a short guide to writing, organising and publishingPlain

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.

•
Pages — .md and .mdx files, up to 1 MB each.
•
Config — your 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).
•
Images — PNG, JPEG, GIF, WebP and SVG. SVGs are cleaned of scripts.

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

LimitValue
Upload50 MB
Unpacked100 MB
An image5 MB
An SVG512 KB
Files in a project2,000
Size of a project200 MB
Uploads30 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:

MessageWhat to do
The upload is too largeLeave out videos and build output, or upload in parts
That file isn't a ZIP we can readZip the folder again (right-click › Compress) and upload the new file
The archive was refusedA file in it expands far more than a document would. Zip the folder again from the original files
The archive contains a linkReplace the symbolic link with the file it points to, and zip again
The archive is password-protectedZip the folder again without a password
This kind of ZIP isn't supportedZip the folder again with your system's built-in compression
No pages foundThe upload has no .md or .mdx files. Pick the folder that holds your Markdown pages
Another upload is still runningWait for the upload into this project to finish, then try again
Too many uploadsEach workspace can upload 30 times an hour. Wait a while and try again
The project would be too largeA project written in Syntext holds up to 200 MB of files. Leave out large images or videos
Too many filesA project written in Syntext holds up to 2,000 files. Upload only the docs folder
A file name isn't allowedRename files whose names start with a dot or contain unusual characters
This project publishes from GitHubCommit 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:

•
Restore brings back the whole revision: every file goes back to how it was then.
•
Tick files and choose Restore selected to bring back only those.

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.

1.
Pick the GitHub account (or Install the Syntext GitHub App), the repository and the Branch — pushes there publish the site. Docs path is optional: leave it empty to use docs/ or the folder the repository already uses; / is the root.
2.
Preview what's there. Nothing is written yet.
◦
An empty folder: This folder is empty. Your N Syntext pages can go in.
◦
A folder with docs: how many pages each side has, how many are identical and how many differ, with the differing files listed (up to 20), and any files that can't come across.
3.

Choose what to keep. You get two choices, depending on what the folder holds:

ChoiceOffered whenWhat happens
Push my pages to the repoThe folder is emptyOne commit adds your Syntext pages to the branch. From then on, pushes publish the site
Open a pull requestThe folder is emptyReview the pages in a pull request first. The site keeps publishing from Syntext until it's merged
Use the repo's pagesThe folder has docsNothing 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 docsYour 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.

4.
Done. GitHub is now the source (with View commit), or Pull request #N is open.

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.

•
Merge it and the project switches to GitHub and builds the merge.
•
Close it without merging and Content source shows The pull request was closed. The project stays in Syntext.
•
Cancel the link stops waiting. The site keeps publishing from Syntext, and the pull request stays open on GitHub — close it there.

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

TaskEndpoint
Create from a templateCreate Project with template — see List Templates
Save draftsSave Pages, with publish: true to publish too
UploadImport Content
PublishPublish Content
History and restoreContent History, Restore Revision
Move to GitHubPreview GitHub Link, Connect GitHub
Back to SyntextDisconnect 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.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext