Skip to content

Commit

Permalink
rewrite with sections
Browse files Browse the repository at this point in the history
  • Loading branch information
@martyndavies
martyndavies committed Aug 21, 2024
1 parent a472851 commit ae3a5c4
Showing 1 changed file with 72 additions and 58 deletions.
130 changes: 72 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,84 +2,48 @@

<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/zudoku-logo-light.svg" width=630>
<img alt="Zudoku Docs & Developer Portal" src="./assets/zudoku-logo-dark.svg" width=630>
<a href="https://zudoku.dev" alt="Zudoku"><img alt="Zudoku Docs & Developer Portal" src="./assets/zudoku-logo-dark.svg" width=630></a>
</picture>

API documentation should always be **free**.
<p align="center">
<a aria-label="Made with love by Zuplo" href="https://zuplo.com"><img src="https://img.shields.io/badge/made_with_❤️_by-zuplo-FF00BD"></a>
<a aria-label="Zudoku Version" href="https://www.npmjs.com/package/zudoku"><img alt="" src="https://img.shields.io/npm/v/zudoku
"></a>
<a aria-label="Create Zudoku App Version" href="https://www.npmjs.com/package/create-zudoku-app"><img alt="" src="https://img.shields.io/npm/v/create-zudoku-app?label=cli
"></a>
<a aria-label="License" href="https://github.com/zuplo/zudoku/license.md"><img alt="" src="https://img.shields.io/badge/license-mit-green"></a>
</p>
<h2>API documentation should always be free.</h2>

[![MIT License](https://img.shields.io/badge/license-mit-green?style=for-the-badge)](https://github.com/zuplo/zudoku/license.md)
[![Zudoku Version](https://img.shields.io/npm/v/zudoku?style=for-the-badge)](https://www.npmjs.com/package/zudoku)
[![Create Zudoku App Version](https://img.shields.io/npm/v/create-zudoku-app?label=cli&style=for-the-badge)](https://www.npmjs.com/package/create-zudoku-app)
[![Made with love by Zuplo](https://img.shields.io/badge/made_with_❤️_by-zuplo-FF00BD?style=for-the-badge)](https://zuplo.com)

</div>

# Introduction

**Zudoku** (pronounced "zoo-doh-koo") is an open-source, highly customizable API documentation framework for building quality developer experiences.
**Zudoku** (pronounced _"zoo-doh-koo"_) is an open-source, highly customizable API documentation framework for building quality developer experiences.

Because building great API documentation should always be:

✅ Free<br />
✅ OpenAPI powered<br />
✅ Programmable

Zudoku supports both OpenAPI and GraphQL schemas and is extended via plugins that include features like static content, authentication, monetization, or anything else you can think of.

Zudoku can use both OpenAPI and GraphQL schemas and is extended via plugins that include features like static content, authentication, monetization, or anything else you can think of.

**Test Zudoku with your own API right now at [zudoku.dev](https://zudoku.dev).**

## Installation



## Use Cases

- Documentation
- API Documentation
- OpenAPI Reference
- GraphQL Reference
- Internal Documentation
- Developer Portal: Generate API Keys, Inspect Logs, etc.
## 🤩 Try it
**Test Zudoku with your own API right now at [zudoku.dev](https://zudoku.dev)** and see how good your documentation can look!

**or any combination of these**
## ⚙️ Installation

## Features
You can use the CLI to generate a new project or use it standalone as a React component.

- Static [MDX pages](https://mdxjs.com/) to document your things 📖
- Generates documentation based on single or multiple OpenAPI schemas <img src="https://emojis.slackmojis.com/emojis/images/1643514263/2320/graphql.png" height="18" />
- OpenAPI 3.x, (working on OpenAPI 4)
- Load spec from disk or URL
- Generates docs based on your GraphQL Schema <img src="https://emojis.slackmojis.com/emojis/images/1681900279/65279/openapi.png?1681900279" height="18" />
- Supports Authentication. Bring your users right into your docs
- OpenID
- OAuth2
- Integrated Playground with Authentication
- Fast & simple to run
- Highly composable with sensible defaults
### ⚡️ Quick start

## Roadmap

- ✅ OpenAPI Support
- ✅ Test Console
- ✅ Authentication
- ✅ MDX Support
- ✅ Static Page Support
- GraphQL Support

# Getting Started

We've made it easy to get started with Zudoku. You can use the CLI to generate a new project or use it as a React component.

## Start from template
Fire up your new API docs from out getting started template:

```
npx create-zudoku-app@latest
```

## Using as Standalone
### 📦 Standalone via CDN

Add the package and styles to your `<head>` and pass the URL for your API schema to the `data-api-url` property, as shown here:

```html
<!doctype html>
Expand All @@ -98,13 +62,63 @@ npx create-zudoku-app@latest
</html>
```

# Contributing
### 🧱 Getting started templates
To get started with some of the features Zudoku offers you can use one of these [example templates](https://github.com/zuplo/zudoku/tree/main/examples):

| Template | What it does |
| -------- | ----------- |
| [many-apis](https://github.com/zuplo/zudoku/tree/main/examples/many-apis) | Using more than one OpenAPI document with Zudoku |
|[with-auth0](https://github.com/zuplo/zudoku/tree/main/examples/with-auth0) | Authenticate users in docs with the Auth0 plugin |
| [with-config](hhttps://github.com/zuplo/zudoku/tree/main/examples/with-config) | Barebones config, ready for you to setup how you like |
| [with-vite-config](https://github.com/zuplo/zudoku/tree/main/examples/with-vite-config) | Use Zudoku with your Vite config (Advanced)|

# ✨ Features

## Run locally
- <img src="https://avatars3.githubusercontent.com/u/16343502?v=3&s=200" width=16 height=16>&nbsp;</img>Generate documentation from a single or multiple [OpenAPI](https://swagger.io/specification/) schema
- <img src="https://raw.githubusercontent.com/graphql/graphql-playground/main/packages/graphql-playground-electron/static/icons/icon.ico" width=16 height=16>&nbsp;</img>Generate documentation based on [GraphQL](https://graphql.org/) schema
- 📄 Create static [MDX pages](https://mdxjs.com/) for anything you want to document
- 🔐 Integrate your users with authentication via OpenID or OAuth2
- 🧪 Let users test their API calls using the Integrated Playground (includes authentication!)

To run the project locally, you can use the following commands:
Zudoku is quick to implement, easy to configure and is highly composable with sensible defaults.

## Zudoku use cases

Zudoku is a flexible and highly customizable framework so it can be used to create many things, including:

- Standalone documentation websites
- OpenAPI or GraphQL schema powered API documentation
- A developer portal with combined documentation and fully function API reference with authentication, testing and support for your user accounts.
- Internal documentation

# 🎓 Examples

- [Rick & Morty API](https://zudoku.zuplopreview.net/demo?api-url=https://rickandmorty.zuplo.io/openapi.json)
- [Zuplo API Documentation](https://docs-zudoku.pages.dev/)

# 🎯 Motivation


# 🔧 Contributing

Contributions are absolutely welcome! You can start contributing by cloning this repository and running:

```
pnpm install
pnpm dev
```

## Prerequisites
To work develop and contribute to Zudoku you will need:

- [Node.js](https://nodejs.org/) >= v20.0.0
- [Git](https://git-scm.com/)
- [pnpm](https://pnpm.io/installation)

More detail on the process for contributing can be found in the [contributing guide](CONTRIBUTING.md).

# Changelog
Details of the latest updates to Zudoku can be found in the [changelog](CHANGELOG.md).

# License
Zudoku is licensed under MIT. See the full [LICENSE].

0 comments on commit ae3a5c4

Please sign in to comment.