Skip to content
This repository has been archived by the owner on Jun 1, 2019. It is now read-only.

relocate docs content to cms-www repo #58

Merged
merged 3 commits into from
Nov 27, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@ dist/
.DS_Store
node_modules
npm-debug.log
yarn-error.log
7 changes: 2 additions & 5 deletions gulpfile.babel.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,18 +14,15 @@ import BrowserSync from "browser-sync";
import webpack from "webpack";
import webpackConfig from "./webpack.conf";

import markWithMagic from './markdown.config.js';

const browserSync = BrowserSync.create();
const hugoBin = "hugo";
const defaultArgs = ["-d", "../dist", "-s", "site", "-v"];

gulp.task("hugo", (cb) => buildSite(cb));
gulp.task("hugo-preview", (cb) => buildSite(cb, ["--buildDrafts", "--buildFuture"]));
gulp.task("docs", (cb) => markWithMagic())

gulp.task("build", ["css", "docs", "js", "fonts", "images", "hugo"]);
gulp.task("build-preview", ["css", "docs", "js", "fonts", "images", "hugo-preview"]);
gulp.task("build", ["css", "js", "fonts", "images", "hugo"]);
gulp.task("build-preview", ["css", "js", "fonts", "images", "hugo-preview"]);

gulp.task("css", () => (
gulp.src("./src/css/**/*.css")
Expand Down
33 changes: 0 additions & 33 deletions markdown.config.js

This file was deleted.

7 changes: 2 additions & 5 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@
"build": "gulp build",
"build-preview": "gulp build-preview",
"start": "gulp server",
"lint": "eslint src",
"docs": "node markdown.config.js"
"lint": "eslint src"
},
"author": "",
"license": "MIT",
Expand Down Expand Up @@ -49,7 +48,5 @@
"whatwg-fetch": "^1.0.0",
"yamljs": "^0.2.8"
},
"devDependencies": {
"markdown-magic": "^0.1.13"
}
"devDependencies": {}
}
62 changes: 60 additions & 2 deletions site/content/docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,64 @@
title: Architecture
position: 9
---
<!-- AUTO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/netlify/netlify-cms/master/docs/architecture.md) -->

<!-- AUTO-GENERATED-CONTENT:END -->
# Technical Architecture

Netlify CMS is a React application, using Redux for state management with immutable data structures (immutable.js).

The core abstractions for content editing are `collections`, `entries` and `widgets`.

Each `collection` represents a collection of entries. This can either be a collection of similar entries with the same structure, or a set of entries where each has its own structure.

The structure of an entry is defined as a series of fields, each with a `name`, a `label`, and a `widget` .

The `widget` determines the UI widget that the content editor will use when editing this field of an entry, as well as how the content of the field is presented in the editing preview.

Entries are loaded and persisted through a `backend` that will typically represent a `git` repository.

## State shape / reducers
**Auth:** Keeps track of the logged state and the current user.

**Config:** Holds the environment configuration (backend type, available collections and fields).

**Collections** List of available collections, their fields and metadata information.

**Entries:** Entries for each field.

**EntryDraft:** Reused for each entry that is edited or created. It holds the entry's temporary data until it's persisted on the backend.

**Medias:** Keeps references to all media files uploaded by the user during the current session.

## Selectors
Selectors are functions defined within reducers used to compute derived data from the Redux store. The available selectors are:

**selectEntry:** Selects a single entry, given the collection and a slug.

**selectEntries:** Selects all entries for a given collection.

**getAsset:** Selects a single AssetProxy object for the given URI.

## Value Objects
**AssetProxy:** AssetProxy is a Value Object that holds information regarding an asset file (such as an image, for example), whether it's persisted online or held locally in cache.

For a file persisted online, the AssetProxy only keeps information about its URI. For local files, the AssetProxy will keep a reference to the actual File object while generating the expected final URIs and on-demand blobs for local preview.

The AssetProxy object can be used directly inside a media tag (such as `<img>`), as it will always return something that can be used by the media tag to render correctly (either the URI for the online file or a single-use blob).

## Components structure and Workflows
Components are separated into two main categories: Container components and Presentational components.

### Entry Editing
For either updating an existing entry or creating a new one, the `EntryEditor` is used and the flow is the same:
* When mounted, the `EntryPage` container component dispatches the `createDraft` action, setting the `entryDraft` state to a blank state (in case of a new entry) or to a copy of the selected entry (in case of an edit).
* The `EntryPage` will also render widgets for each field type in the given entry.
* Widgets are used for editing entry fields. There are different widgets for different field types, and they are always defined in a pair containing a `control` and a `preview` component. The control component is responsible for presenting the user with the appropriate interface for manipulating the current field value, while the preview component is responsible for displaying the value with the appropriate styling.

#### Widget components implementation
The control component receives three (3) callbacks as props: `onChange`, `onAddAsset`, and `onRemoveAsset`.
* onChange (required): Should be called when the users changes the current value. It will ultimately end up updating the EntryDraft object in the Redux Store, thus updating the preview component.
* onAddAsset & onRemoveAsset (optionals): If the field accepts file uploads for media (images, for example), these callbacks should be invoked with a `AssetProxy` value object. `onAddAsset` will get the current media stored in the Redux state tree while `onRemoveAsset` will remove it. AssetProxy objects are stored in the `Medias` object and referenced in the `EntryDraft` object on the state tree.

Both control and preview widgets receive a `getAsset` selector via props. Displaying the media (or its URI) for the user should always be done via `getAsset`, as it returns an AssetProxy that can return the correct value for both medias already persisted on the server and cached media not yet uploaded.

The actual persistence of the content and medias inserted into the control component is delegated to the backend implementation. The backend will be called with the updated values and a list of assetProxy objects for each field of the entry, and should return a promise that can resolve into the persisted entry object and the list of the persisted media URIs.
95 changes: 95 additions & 0 deletions site/content/docs/auth-backends.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
title: Auth & Backends
position: 8
---

# Auth & Backends

Netlify CMS stores content in your GitHub repository. (GitLab and Bitbucket coming soon!) In order for this to work, you need to authenticate with GitHub, and that requires a server. We have a few options for handling this.

## Git Gateway with Netlify Identity

[Git Gateway](https://github.com/netlify/git-gateway) is a Netlify open source project that allows you to add editors to your site CMS without giving them direct push access to your GitHub repository. [Netlify Identity](https://www.netlify.com/docs/identity/) service handles the authentication and provides a simple interface for user management. The Netlify CMS [Test Drive](/test-drive/) is a working example of this backend.

To use it in your own project, follow these steps:

1. Head over to the [Netlify Identity docs](https://www.netlify.com/docs/identity) and follow the
steps to get started.
2. Add the following lines to your `config.yml` file:

``` yaml
backend:
name: git-gateway
accept_roles: #optional - accepts all users if left out
- admin
- editor
```

3. Optionally, you can assign roles to users in your Netlify dashboard, and then limit which
roles can access the CMS by defining the `accept_roles` field in the `config.yml` example above.
Otherwise `accept_roles` can be left out, and all Netlify Identity users on your site will have access.

## Git Gateway without Netlify

You can use [Git Gateway](https://github.com/netlify/git-gateway) without Netlify by setting up your own Git Gateway server and connecting it with your own instance of [GoTrue](https://www.gotrueapi.org) (the open source microservice that powers Netlify Identity), or with any other identity service that can issue JSON Web Tokens (JWT).

To configure in Netlify CMS, use the same `backend` settings in your `config.yml` file as described in Step 2 of the [Git Gateway with Netlify Identity](#git-gateway-with-netlify-identity) instructions above.

## GitHub Backend

The GitHub backend allows CMS users to log in directly with their GitHub account. Note that the
user's GitHub account must have push access to your content repository for this to work.

Because Github [requires a
server](https://github.com/netlify/netlify-cms/issues/663#issuecomment-335023723) for
authentication, Netlify facilitates basic GitHub authentication.

To enable it:

1. Follow the authentication provider setup steps in the [Netlify
docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
2. Add the following lines to your `config.yml` file:

``` yaml
backend:
name: github
repo: owner-name/repo-name # Path to your Github repository
```


### External OAuth Clients
If you would like to facilitate your own OAuth authentication rather than use Netlify's service, you
can use one of the community-maintained projects below. Feel free to [submit a pull request](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) if you'd like to add yours!


| Author | Supported Git hosts | Languages | Link |
|------------|---------------------------|-----------|---------------------------------------------------------------------|
| @vencax | GitHub, GitHub Enterprise | Node.js | [Repo](https://github.com/vencax/netlify-cms-github-oauth-provider) |

Check each project's documentation for instructions on how to configure it.


## Bitbucket and GitLab Support

Netlify CMS is meant to be platform agnostic, so we’re always looking to expand the ecosystem and
find new ways to use it. Check out our active PRs in progress for
[Bitbucket](https://github.com/netlify/netlify-cms/pull/525) and
[Gitlab](https://github.com/netlify/netlify-cms/pull/517) backends.

Git Gateway could also be modified to support these Git hosts. If you're interested, you can file an
issue (or a pull request!) in the [git-gateway repo](https://github.com/netlify/git-gateway).

## Options

Both `git-gateway` and `github` backends allow some additional optional fields for certain use
cases. A full reference is below. Note that these are properties of the `backend` field, and should
be nested under that field.

| Field | Default | Description |
|----------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `repo` | none | **Required** for `github` backend; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`. |
| `accept_roles` | none | `git-gateway` only. Limits CMS access to your defined array of user roles. Omitting this field gives access to all registered users. |
| `branch` | `master` | The branch where published content is stored. All CMS commits and PRs are made to this branch. |
| `api_root` | `https://api.github.com` (ignored for `git-gateway` backend) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise. |
| `site_domain` | `location.hostname` (or `cms.netlify.com` when on `localhost`) | Sets the `site_id` query param sent to the API endpoint. Non-Netlify auth setups will often need to set this for local development to work properly. |
| `base_url` | `https://api.netlify.com` | OAuth client URL for the `github` backend. **Required** when using an external OAuth server with the `github` backend. |
11 changes: 9 additions & 2 deletions site/content/docs/contributor-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@
title: Contributing
position: 10
---
<!-- AUTO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/netlify/netlify-cms/master/docs/contributor-guide.md) -->

<!-- AUTO-GENERATED-CONTENT:END -->
# Welcome, contributors!

We're hoping that Netlify CMS will do for the [JAMstack](https://www.jamstack.org) what WordPress did for dynamic sites back in the day. We know we can't do that without building a thriving community of contributors and users, and we'd love to have you join us.

While we work on building this page (and you can help!), here are some links with more information about getting involved:

* [Project Milestones](https://github.com/netlify/netlify-cms/milestones)
* [Code of Conduct](https://github.com/netlify/netlify-cms/blob/master/CODE_OF_CONDUCT.md)
* [Setup instructions and Contribution Guidelines](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md)
7 changes: 0 additions & 7 deletions site/content/docs/custom-authentication.md

This file was deleted.

Loading