Update Authentication doc to cover all backends #751
Conversation
|
@verythorough I reviewed your PR by opening a PR against your PR. You can comment on my PR about your PR on my PR, or right here on your PR, or by opening another PR against my PR against your PR. Or whatever :) Love the bread-dog! Seriously though, we'll continue discussion here. Preview link: https://preview-auth-doc-update--netlify-cms-www.netlify.com/docs/authentication-backends/ |
|
lol, thanks. Not sure why I had such a block with this one, but your edits help a lot. I like the numbered steps. I was this close to using the table format for the options, but the layout makes them a bit hard to read. I may futz with the styling a bit to make that better, because I think we'd benefit from more tables throughout the docs. I'm going to merge your PR into this one and comment/edit in here from that point. |
|
I think the table readability issue is just due to our content column being so narrow. We should spread the max by a good 25% at least. |
|
Long line lengths hurt readability. Recommendations for ideal line length vary, but are generally below 85 characters per line, and typically 75 or lower. The current template has max line lengths in the 90s, so I wouldn't want to widen it much, if at all. |
|
I wonder if it's possible to let the table flow to a bigger |
|
We could make text a little bigger. Again, drawing inspiration from reactjs.org/docs. (and maybe table text a little smaller) |
|
The React docs appear to be using 42em content width with a 17px body font (not counting the lede at the beginning of the page), while netlifycms.org is 45em and 18px, so they're kinda the same size already. The table text is already significantly smaller than the body font, so I'm thinking something more along the lines of reducing the table cell padding. Just removing the 24px side padding produces a significantly more readable result: I plan to do a little more than that, though, to keep it clear and pretty. |
verythorough
force-pushed
the
docs-authentication
branch
from
cf8c9a0
to
9cacb21
Compare
There was a problem hiding this comment.
I made some edits to the doc, and now consider it ready to merge, pending review.
I've added line comments to explain some of the changes.
The preview has updated to include the changes: https://preview-auth-doc--netlify-cms-www.netlify.com/docs/authentication-backends/
@flaturtha, @eamonnbell Would you like to take a look?
docs/authentication-backends.md
Outdated
| Netlify CMS stores content in your GitHub repository (GitLab and Bitbucket coming soon!). You'll | ||
| need to sign in to your GitHub account through the CMS for this to work, and it requires a server. | ||
| We have a few options for handling this. | ||
| 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. |
There was a problem hiding this comment.
I liked "You need to sign in to your GitHub account," but it doesn't actually apply to Git Gateway. "Authenticate" is more formal, but also more accurate.
docs/authentication-backends.md
Outdated
|
|
||
| Using it in your own project is simple: | ||
| To use it in your own project, follow these steps: |
There was a problem hiding this comment.
I try to avoid using words like "simple," "easy," or "just do x" in docs, since the reader may disagree and/or feel judged.
| name: git-gateway | ||
| accept_roles: #optional - accepts all users if left out | ||
| - admin | ||
| - editor |
There was a problem hiding this comment.
Matched the format to our other yaml code snippets
| backend: | ||
| name: github | ||
| repo: owner-name/repo-name # Path to your Github repository | ||
| ``` |
There was a problem hiding this comment.
I had to indent the code blocks one more tab to make them properly display in the numbered list, here and in the Git Gateway steps.
(Side note: we should take a look at how the rich text editor marks up code blocks inside of lists, and be sure they produce the desired output in most cases.)
docs/authentication-backends.md
Outdated
| request](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) if you'd like to add | ||
| yours! | ||
| 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! | ||
|
|
There was a problem hiding this comment.
On re-reading, this paragraph made more sense under the External OAuth Clients heading than before it.
docs/authentication-backends.md
Outdated
| |----------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `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. | |
There was a problem hiding this comment.
I removed the "Required" column because it took up a lot of space, and as it turns out, none of them are required in all cases. Instead, I added "Required for x" in the description.
I also added accept_roles so we now cover all possible fields (except name which felt kind of weird to include—open to adding, though).
verythorough
changed the title
|
The preview also now includes style changes from netlify/netlify-cms-www#53 (but the preview in that PR does not include the changes from this one 😝 ) |
|
I think this is ready to merge. Once merged, we'll want to check the preview for netlify/netlify-cms-www#57, and then merge that to get the changes applied to netlifycms.org. |
Note that this docs update (or any other docs edit) will not display on netlifycms.org until #749 is resolved.Resolved with 83a1d34- Summary
As described in #600, this adapts the existing custom-authentication.md to a more general authentication-backends.md, with instructions and reference material for all existing backend options.
I'd really love feedback on this. I struggled with explaining concepts and contraints without creating huge blocks of text people would skip over. I'm uncertain about the "More config options" section at the bottom, particularly because a few of those are
github-specific. (Will they apply togitlabandbitbucket?) Also, unlike the others options,branchseems common enough that it might be worth putting in the config samples for both backends.- Test plan
I generated a preview you can check out,
but had to break the Extending Widgets doc in that branch so the preview build would compete. As mentioned above, #749 will have to be resolved before any docs edits appear on netlifycms.org.(resolved)- Description for the changelog
Updated Authentication & Backends documentation
- A picture of a cute animal (not mandatory but encouraged)
For Halloween: a pure bread shiba