This plugin adds a client-side text editor to your Docusaurus application, allowing users to propose changes to any of your Markdown files without the need to know Markdown or GitHub. It uses the GitHub API to fork your content repository for the user, commit any progress and create pull requests to the upstream repository.
Some functionality is either not implemented or needs fixing. Please have a look at open issues to join discussions and see what needs fixing. |
This plugin uses the GitHub OAuth web application flow to get authorization from the user to interact with GitHub on behalf of the user.
To enable GitHub authorization:
- Set up a GitHub OAuth app and note down the client ID and client secret.
- Set up an authorization server that swaps a users authorization code for an access token using the client secret. Have a look at Gatekeeper for an easy authorization server setup.
Then add this plugin to your Docusaurus project:
yarn add @jlvandenhout/docusaurus-plugin-docs-editor
Enable the plugin in your Docusaurus configuration and update the settings with the client ID and the URL to your authorization server (see configuration for further options):
module.exports = {
...
plugins: [
[
'@jlvandenhout/docusaurus-plugin-docs-editor',
{
authorizationClientId: '99999999999',
authorizationTokenUrl: 'http://localhost:9999/authorization/',
},
],
],
};
After building your Docusaurus application, you should now find the link to edit a page right next to where you would normally find the link to GitHub in all your Markdown generated pages!
Option | Required | Explanation |
---|---|---|
authorizationClientId | x | The client ID of the GitHub OAuth app. |
authorizationTokenUrl | x | The URL to your authorization server endpoint. |
authorizationMethod | The request method to use (GET or POST). Defaults to 'GET'. | |
contentOwner | The owner of the repository. Defaults to siteConfig.organizationName . |
|
contentRepo | The name of the repository. Defaults to siteConfig.projectName . |
|
contentDocsPath | The path to the documentation in the repository. Defaults to 'docs'. | |
contentStaticPath | The path to the static directory in the repository. Defaults to 'static'. | |
editorPath | The editor endpoint. Defaults to 'edit'. |
This repository provides a preview
directory containing the live preview repository and Gatekeeper repository as submodules. They are configured using an .env
file (see the .env.example
file). You will still need to set up a GitHub OAuth app yourself using http://localhost
as authorization callback URL.
For a local setup, first clone this repository including submodules:
git clone --recurse-submodules https://github.com/jlvandenhout/docusaurus-plugin-docs-editor.git
cd docusaurus-plugin-docs-editor
Then copy the .env.example
file to .env
and update the OAUTH_CLIENT_ID
and OAUTH_CLIENT_SECRET
with the values of your GitHub OAuth app.
Now you can install all dependencies and start both the website and the authorization server by doing:
yarn install
yarn start
This will:
- Build the plugin.
- Configure both the website and the authorization server with the environment variables from the
.env
file. - Start watching for any changes to the plugin or website source code.
- Automatically rebuild any changes.