diff options
Diffstat (limited to 'docs/dev')
| -rw-r--r-- | docs/dev/api.md | 53 | ||||
| -rw-r--r-- | docs/dev/getting-started.md | 17 | ||||
| -rw-r--r-- | docs/dev/ot.md | 9 | ||||
| -rw-r--r-- | docs/dev/webpack.md | 11 |
4 files changed, 42 insertions, 48 deletions
diff --git a/docs/dev/api.md b/docs/dev/api.md index 4c1365b5..fbbdae83 100644 --- a/docs/dev/api.md +++ b/docs/dev/api.md @@ -5,39 +5,38 @@ For code-autogeneration there is an OpenAPIv3-compatible description available [ ## Notes These endpoints create notes, return information about them or export them. -You have to replace _\<NOTE\>_ with either the alias or id of a note you want to work on. +You have to replace *\<NOTE\>* with either the alias or id of a note you want to work on. -| Endpoint | HTTP-Method | Description | -|---|---|---| -| `/new` | `GET` | **Creates a new note.**<br>A random id will be assigned and the content will equal to the template (blank by default). After note creation a redirect is issued to the created note. | -| `/new` | `POST` | **Imports some markdown data into a new note.**<br>A random id will be assigned and the content will equal to the body of the received HTTP-request. The `Content-Type: text/markdown` header should be set on this request. | -| `/new/<ALIAS>` | `POST` | **Imports some markdown data into a new note with a given alias.**<br>This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](../configuration-env-vars.md#users-and-privileges) is enabled. | -| `/<NOTE>/download` or `/s/<SHORT-ID>/download` | `GET` | **Returns the raw markdown content of a note.** | -| `/<NOTE>/pdf` | `GET` | **Returns a generated pdf version of the note.**<br>If pdf-support is disabled, a HTTP 403 will be returned.<br>_Please note: Currently pdf export is disabled generally because of a security problem with it._ | -| `/<NOTE>/publish` | `GET` | **Redirects to the published version of the note.** | -| `/<NOTE>/slide` | `GET` | **Redirects to the slide-presentation of the note.**<br>This is only useful on notes which are designed to be slides. | -| `/<NOTE>/info` | `GET` | **Returns metadata about the note.**<br>This includes the title and description of the note as well as the creation date and viewcount. The data is returned as a JSON object. | -| `/<NOTE>/revision` | `GET` | **Returns a list of the available note revisions.**<br>The list is returned as a JSON object with an array of revision-id and length associations. The revision-id equals to the timestamp when the revision was saved. | -| `/<NOTE>/revision/<REVISION-ID>` | `GET` | **Returns the revision of the note with some metadata.**<br>The revision is returned as a JSON object with the content of the note and the authorship. | -| `/<NOTE>/gist` | `GET` | **Creates a new GitHub Gist with the note's content.**<br>If [GitHub integration](../configuration-env-vars.md#github-login) is configured, the user will be redirected to GitHub and a new Gist with the content of the note will be created. | +| Endpoint | HTTP-Method | Description | +| ---------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `/new` | `GET` | **Creates a new note.**<br>A random id will be assigned and the content will equal to the template (blank by default). After note creation a redirect is issued to the created note. | +| `/new` | `POST` | **Imports some markdown data into a new note.**<br>A random id will be assigned and the content will equal to the body of the received HTTP-request. The `Content-Type: text/markdown` header should be set on this request. | +| `/new/<ALIAS>` | `POST` | **Imports some markdown data into a new note with a given alias.**<br>This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](../configuration-env-vars.md#users-and-privileges) is enabled. | +| `/<NOTE>/download` or `/s/<SHORT-ID>/download` | `GET` | **Returns the raw markdown content of a note.** | +| `/<NOTE>/pdf` | `GET` | **Returns a generated pdf version of the note.**<br>If pdf-support is disabled, a HTTP 403 will be returned.<br>*Please note: Currently pdf export is disabled generally because of a security problem with it.* | +| `/<NOTE>/publish` | `GET` | **Redirects to the published version of the note.** | +| `/<NOTE>/slide` | `GET` | **Redirects to the slide-presentation of the note.**<br>This is only useful on notes which are designed to be slides. | +| `/<NOTE>/info` | `GET` | **Returns metadata about the note.**<br>This includes the title and description of the note as well as the creation date and viewcount. The data is returned as a JSON object. | +| `/<NOTE>/revision` | `GET` | **Returns a list of the available note revisions.**<br>The list is returned as a JSON object with an array of revision-id and length associations. The revision-id equals to the timestamp when the revision was saved. | +| `/<NOTE>/revision/<REVISION-ID>` | `GET` | **Returns the revision of the note with some metadata.**<br>The revision is returned as a JSON object with the content of the note and the authorship. | +| `/<NOTE>/gist` | `GET` | **Creates a new GitHub Gist with the note's content.**<br>If [GitHub integration](../configuration-env-vars.md#github-login) is configured, the user will be redirected to GitHub and a new Gist with the content of the note will be created. | ## User / History These endpoints return information about the current logged-in user and it's note history. If no user is logged-in, the most of this requests will fail with either a HTTP 403 or a JSON object containing `{"status":"forbidden"}`. -| Endpoint | HTTP-Method | Description | -|---|---|---| -| `/me` | `GET` | **Returns the profile data of the current logged-in user.**<br>The data is returned as a JSON object containing the user-id, the user's name and a url to the profile picture. | -| `/me/export` | `GET` | **Exports a zip-archive with all notes of the current user.** | -| `/history` | `GET` | **Returns a list of the last viewed notes.**<br>The list is returned as a JSON object with an array containing for each entry it's id, title, tags, last visit time and pinned status. | -| `/history` | `POST` | **Replace user's history with a new one.**<br>The body must be form-encoded and contain a field `history` with a JSON-encoded array like its returned from the server when exporting the history. | -| `/history` | `DELETE` | **Deletes the user's history.** | -| `/history/<NOTE>` | `POST` | **Toggles the pinned status in the history for a note.**<br>The body must be form-encoded and contain a field `pinned` that is either `true` or `false`. -| `/history/<NOTE>` | `DELETE` | **Deletes a note from the user's history.** | - +| Endpoint | HTTP-Method | Description | +| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/me` | `GET` | **Returns the profile data of the current logged-in user.**<br>The data is returned as a JSON object containing the user-id, the user's name and a url to the profile picture. | +| `/me/export` | `GET` | **Exports a zip-archive with all notes of the current user.** | +| `/history` | `GET` | **Returns a list of the last viewed notes.**<br>The list is returned as a JSON object with an array containing for each entry it's id, title, tags, last visit time and pinned status. | +| `/history` | `POST` | **Replace user's history with a new one.**<br>The body must be form-encoded and contain a field `history` with a JSON-encoded array like its returned from the server when exporting the history. | +| `/history` | `DELETE` | **Deletes the user's history.** | +| `/history/<NOTE>` | `POST` | **Toggles the pinned status in the history for a note.**<br>The body must be form-encoded and contain a field `pinned` that is either `true` or `false`. | +| `/history/<NOTE>` | `DELETE` | **Deletes a note from the user's history.** | ## CodiMD-server These endpoints return information about the running CodiMD instance. -| Endpoint | HTTP-Method | Description | -|---|---|---| -| `/status` | `GET` | **Returns the current status of the CodiMD instance.**<br>The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more. | +| Endpoint | HTTP-Method | Description | +| --------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/status` | `GET` | **Returns the current status of the CodiMD instance.**<br>The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more. | diff --git a/docs/dev/getting-started.md b/docs/dev/getting-started.md index 9a35b71a..7ed96944 100644 --- a/docs/dev/getting-started.md +++ b/docs/dev/getting-started.md @@ -1,5 +1,4 @@ -Developer Notes -=== +# Developer Notes ## Preparing for running the code @@ -7,20 +6,20 @@ Developer Notes 1. Clone the repository with `git clone https://github.com/codimd/server.git codimd-server` (cloning is the preferred way, but you can also download and unzip a release) + 2. Enter the directory and run `bin/setup`, which will install npm dependencies and create configs. The setup script is written in Bash, you would need bash as a prerequisite. + 3. Setup the [config file](../configuration-config-file.md) or set up [environment variables](../configuration-env-vars.md). - ## Running the Code Now that everything is in place, we can start CodiMD: -4. `yarn run build` will build the frontend bundle. It uses webpack to do that. -5. Run the server with `node app.js` - +1. `yarn run build` will build the frontend bundle. It uses webpack to do that. +2. Run the server with `node app.js` ## Running the Code with Auto-Reload @@ -32,11 +31,11 @@ rebuild the frontend or restart the server if necessary. The commands will stay active in your terminal, so you will need multiple tabs to run both at the same time. -4. Use `yarn run dev` if you want webpack to continuously rebuild the frontend +1. Use `yarn run dev` if you want webpack to continuously rebuild the frontend code. -5. To auto-reload the server, the easiest method is to install [nodemon](https://www.npmjs.com/package/nodemon) - and run `nodemon --watch app.js --watch lib --watch locales app.js`. +2. To auto-reload the server, the easiest method is to install [nodemon](https://www.npmjs.com/package/nodemon) + and run `nodemon --watch app.js --watch lib --watch locales app.js`. ## Structure diff --git a/docs/dev/ot.md b/docs/dev/ot.md index 924be693..a1d0bebe 100644 --- a/docs/dev/ot.md +++ b/docs/dev/ot.md @@ -1,5 +1,4 @@ -Operational Transformation -=== +# Operational Transformation From 0.3.2, we started supporting operational transformation. It makes concurrent editing safe and will not break up other users' operations. @@ -9,6 +8,6 @@ See more at [https://operational-transformation.github.io/](https://operational- And even more in this 2010 article series: -* https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs_21.html -* https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs_22.html -* https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs.html +- <https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs_21.html> +- <https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs_22.html> +- <https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs.html> diff --git a/docs/dev/webpack.md b/docs/dev/webpack.md index 3d35b28a..23bbd7a1 100644 --- a/docs/dev/webpack.md +++ b/docs/dev/webpack.md @@ -1,5 +1,4 @@ -Webpack -=== +# Webpack Webpack is a JavaScript build system for frontend code. You can find out all about it on [the webpack website](https://webpack.js.org/). @@ -15,7 +14,6 @@ The `index` group for example bundles all javascript files and libraries used fo Entrypoints are referenced in the `plugins` section. The `HtmlWebpackPlugin` uses templates in `public/views/includes` to include the path to the generated resources in new templates under `public/views/build`. These templates are then used by the backend to serve HTML to the browser. - **TODO:** Document which entry points are used for what. ## `webpack.htmlexport.js` @@ -24,17 +22,16 @@ Packs all CSS from `public/js/htmlExport.js` to `build/html.min.css`. This file is then downloaded by client-side JS and used to create the HTML. See `exportToHTML()` in `public/js/extra.js`. - ## `webpack.dev.js` The development config uses both common configs, enables development mode and enables "cheap" source maps (lines only). If you need more detailed source maps while developing, you might want to use the `source-maps` option. -See https://webpack.js.org/configuration/devtool/ for details. +See <https://webpack.js.org/configuration/devtool/> for details. ## `webpack.prod.js` The production config uses both common configs and enables production mode. -This automatically enables various optimizations (e.g. UglifyJS). See https://webpack.js.org/concepts/mode/ for details. +This automatically enables various optimizations (e.g. UglifyJS). See <https://webpack.js.org/concepts/mode/> for details. For the global app config, the name of the emitted chunks is changed to include the content hash. -See https://webpack.js.org/guides/caching/ on why this is a good idea. +See <https://webpack.js.org/guides/caching/> on why this is a good idea. For the HTML export config, CSS minification is enabled. |