# Create your site

After you've [installed](<https://zensical.org/docs/get-started/index.md>) Zensical, you can bootstrap your project documentation using the `zensical` executable. Go to the directory where you want your project to be located and enter:

```sh
zensical new .
```

This creates the following structure:

```text
.
├─ .github/workflows
│  └─ docs.yml
├─ docs/
│  ├─ index.md
│  └─ markdown.md
└─ zensical.toml
```

To learn more about the specific files and directories that are generated for you, please consult the usage guide for the [`new` command](<https://zensical.org/docs/usage/new/#usage>).

## Configuration

Zensical comes with many [configuration options](<https://zensical.org/docs/setup/basics/index.md>) that have sensible defaults, which allows to build a documentation site with almost no configuration. [`site_name`](<https://zensical.org/docs/setup/basics/#site_name>) is the only required setting:[^/docs/create-your-site/#1]

```toml
[project]
site_name = "My site"
```

Unless you're building documentation for [offline usage](<https://zensical.org/docs/setup/offline/index.md>), it's strongly recommended to specify the [`site_url`](<https://zensical.org/docs/setup/basics/#site_url>) setting as well, since it's a prerequisite for the following features:

- [Instant navigation](<https://zensical.org/docs/setup/navigation/#instant-navigation>)
- [Instant previews](<https://zensical.org/docs/setup/navigation/#instant-previews>)
- [Custom error pages](<https://zensical.org/docs/customization/#custom-error-pages>)

## Preview as you write

### Zensical Studio

[Zensical Studio](<https://zensical.org/studio>) brings workspace intelligence to **Zensical** and **MkDocs projects** and integrates with Visual Studio Code and similar editors[^/docs/create-your-site/#2]. It gives you a synchronized side-by-side view of your Markdown source and rendered documentation, with the preview updating as you write:

[![Editor](<https://zensical.org/docs/assets/screenshots/editor.png#gh-light-mode-only>)](<https://zensical.org/docs/assets/screenshots/editor.png#gh-light-mode-only>) [![Editor dark](<https://zensical.org/docs/assets/screenshots/editor-dark.png#gh-dark-mode-only>)](<https://zensical.org/docs/assets/screenshots/editor-dark.png#gh-dark-mode-only>)

Zensical Studio provides:

- [Link Intelligence](<https://zensical.org/studio/workflows/link-intelligence/>)

  ---

  Links, anchors, references, and snippets are resolved across the workspace, so they can be navigated, renamed, and kept up to date.
- [Markdown Preview](<https://zensical.org/studio/write/preview/>)

  ---

  A side-by-side preview renders the current Python Markdown document and updates while you edit, so you can stay in your editor while writing.
- [Markdown Formatter](<https://zensical.org/studio/write/formatting/>)

  ---

  A structure-aware formatter for Python Markdown that understands nested extensions such as tabs, admonitions, lists, and code blocks.
- [Markdown Linter](<https://zensical.org/studio/write/linting/>)

  ---

  Workspace-wide diagnostics, including cross-file link tracking and analysis, and structural and prose linting for common Markdown issues.

### Zensical

Zensical includes a web server, so you can preview your documentation site as you write. The server will automatically rebuild the site when you make changes to source files. Start it with:

```sh
zensical serve
```

Point your browser to [localhost:8000](<http://localhost:8000>) and you should see:

[![Creating your site](<https://zensical.org/docs/assets/screenshots/creating-your-site.png#gh-light-mode-only>)](<https://zensical.org/docs/assets/screenshots/creating-your-site.png#gh-light-mode-only>) [![Creating your site dark](<https://zensical.org/docs/assets/screenshots/creating-your-site-dark.png#gh-dark-mode-only>)](<https://zensical.org/docs/assets/screenshots/creating-your-site-dark.png#gh-dark-mode-only>)

## Build your site

When you're finished editing, you can build a static site from your Markdown files with:

```text
zensical build
```

The contents of this directory make up your project documentation. There's no need for operating a database or server, as it is completely self-contained. The site can be hosted on [GitHub Pages](<https://zensical.org/docs/publish-your-site/#github-pages>), a CDN of your choice or your private web space.

If you intend to distribute your documentation as a set of files to be read from a local filesystem rather than a web server (such as in a `.zip` file), please consult the [offline usage](<https://zensical.org/docs/setup/offline/index.md>) guide.

[^/docs/create-your-site/#1]: [`site_name`](<https://zensical.org/docs/setup/basics/#site_name>) is currently required because MkDocs, the static site generator Zensical replaces, requires it. We plan to make this setting optional in a future release.

[^/docs/create-your-site/#2]: Zensical Studio will be supported in more editors in the future, including JetBrains IDEs and Neovim.