* Provide more context in the docs intro page
Closes#22469
The current docs landing page does not include enough context for new
readers. After the general description of Teleport, the rest of the
landing page is series of links, with little guidance for what a new
user should do first (or what an intermediate user should do after
completing the initial setup steps).
This change takes a more narrative approach to the landing page,
briefly describing the content of each top-level docs section and
putting it in context with the rest of the docs. This also helps users
find the right top-level docs section for their needs, since otherwise
the only way to do this is to visit each section.
This change is also more opinionated about which guide new users should
begin with. It recommends the guide to getting started with Teleport
Cloud, since this doesn't require setting up a Teleport cluster and
helps a user register a resource quickly.
The landing page links to the introduction page of each top-level docs
section. If a section does not have an introduction page, this change
adds one.
* Respond to zmb3 feedback
Reorder list items
* Linter fixes
* Respond to alexfornuto PR feedback
* Reorganize early-stage docs sections
Closes#18127
Currently, there are two sections of the docs related to the earliest
stages of setting up Teleport, "Try out Teleport" and "Deploy a
Cluster". While the organization of our top-level docs sections attempts
to correspond to the stages a user goes through when setting up
Teleport, these combine some tasks that should probably be separated:
- **Choosing an edition and deploying a production cluster**: While the
"Deploy a Cluster" section includes our deployment guides as well as
our edition guides, user will likely commit to setting up Teleport
Cloud, Open Source, or Enterprise before they plan a full HA
production deployment.
- **Deploying a production cluster and deploying a small-scale Teleport
cluster:** While the "Deploy a Cluster" section includes the Linux
Server and Digital Ocean 1-Click guides, these two guides are more for
small-scale deployments than full production clusters.
This change improves the early-stage docs experience for new Teleport
users by:
Splitting the "Deploy a Cluster" section
----------------------------------------
The "Deploy a Cluster" section includes subsections related to choosing
a Teleport edition as well as subsections related to deploying a
production cluster. The problem with this approach is that it leaves no
room for adding introductory guides to help users with these two
purposes.
By splitting the "Deploy a Cluster" section into two top-level sections,
one related to choosing an edition and the other to dpeloying to
production, we can add introductory pages that put the subsections of
these sections in context.
_This change accompanies the work on #16751 to write a general guide to
HA Teleport deployments, since the new guide will have a prominent
place in the reorganized "Deploy a Cluster" section._
Adding introductory pages
-------------------------
Sections related to getting started with Teleport, "Try out Teleport"
and "Deploy a Cluster", were missing introductory pages. This change
adds them, and also adds one to the new "Choose an Edition" section.
Moving the Linux Server and Digital Ocean guides
------------------------------------------------
Move these to "Try out Teleport". The Digital Ocean guide didn't fit
with the rest of the deployment guides, since it's not about
architecting an HA deployment.
This is also a better home for the "Linux Server" guide, so this change
moves that as well.
Removing the "getting-started.mdx" page
---------------------------------------
This page is not reachable via the navigation menu.
* Respond to PR feedback
* Respond to PR feedback
Also minor text tweaks
* Organize docs guide sections chronologically
This change aims to make docs navigation easier by organizing some docs
sections according to the sequence of steps a user would take to set up
Teleport.
The current docs organization uses a variety of categories and schemes
to organize the docs. For example, there is a "Home" section that
includes the Changelog, Installation page, and Getting Started guides; a
"Setup" section that includes references and admin guides; and
edition-specific sections (Enterprise, Cloud). For a user who is setting
up Teleport--or who has already done some setup work and wants more
advanced instructions--it's difficult to know where in the docs to find
the right information.
This change organizes our how-to guides into the following categories
that describe the process of setting up Teleport:
- Try out Teleport
- Deploy a Cluster (including choosing an edition)
- Configure Access (including SSO, RBAC, and Access Requests)
- Manage your Cluster (admin guides, operations, etc.)
- Use Teleport (this section already exists)
I moved the Reference section after this chronology, since users can
access the reference guides anywhere in the setup process.
As part of the change, I have also moved the content from the
"Enterprise" and "Cloud" sections into "Deploy a Cluster", since this
content has to do with how to deploy a specific edition of Teleport.
Note that this change does _not_ attempt to reorganize our
protocol-specific sections. While adding resources is part of the
Teleport setup process, we have a lot of content in our
protocol-specific sections, and moving it all into a single section
related to adding resources to a cluster would (a) exceed the maximum
depth for subsections in the nav bar and (b) cause more confusion than
it alleviates.
* Respond to PR feedback
- Create a "Compliance Frameworks" section of "Configure Access" with
the FedRAMP and SOC 2 guides
- Rename "Use Teleport" to "Connect your Client"
- Move the database GUI client guide into "Connect your Client"
* Add redirects
* Fix linter issues
This change replaces all `Tile`s in the docs with lists of links. This
achieves two things:
- Helps us move toward a more text-focused look and feel for the docs.
See gravitational/docs#93.
- Makes it easier to reorganize the docs. Currently, there's no linting
for internal links in `Tile` hrefs (See gravitational/docs#100).
I used this script to edit each docs page, invoking the script for all
MDX files in docs/pages:
```
gawk '
BEGIN{inopentag=0; indesc=0; desc=""; title=""; href="";}
/<\/?TileSet>/{next;}
/<Tile/ {
inopentag=1;
}
inopentag==1 && /title=/{
title=gensub(/.*title="([^"]+)".*/, "\\1", "g", $0);
}
inopentag==1 && /href=/{
href=gensub(/.*href="([^"]+)".*/, "\\1", "g", $0);
}
inopentag==1 && />/ {
inopentag=0;
indesc=1;
next;
}
indesc==1 && !/<\/Tile/{
gsub(/(\n|\t|\s{2,})/," ",$0);
desc=desc ($0);
next;
}
/<\/Tile/{
print "- [" title "](" href "):" desc;
indesc=0;
desc="";
title="";
href="";
next;
}
inopentag==0 && indesc==0{ print $0 }
' $1 > "$1.tmp";
cat "$1.tmp" > "$1";
rm "$1.tmp";
```
I then cleaned up each file changed by the script and fixed any
incorrect URLs.
Currently, the main body content of the docs home page links to
sections related to individual resources (Server Access, Application
Access, etc.). For users visiting the docs for the first time, it's
difficult to determine what is involved in getting started with
Teleport.
This change organizes the docs landing page to imply that there is a
progression from one stage of the user's setup to the next.
See #12787
- Add headings for different stages of setting up Teleport.
- Add links to a Getting Started guide for each edition that includes a
"scope" query so users are given the appropriate scope (this partially
addresses #12773).
- Edit the initial list of Teleport benefits to be more general and
encompass more functionality.
- Very light copy-editing of the text in the tile lists at the bottom
of the page.
Add the WebAuthn Access Control guide and tweak various pages that mention U2F
to either refer to WebAuthn or use more generic terms.
* Added `/docs/access-controls/guides/webauthn/` (branched from u2f.mdx)
* Added `webauthn` section to reference configuration (`u2f` kept unchanged)
* U2F access control guide moved under the "References" section and removed
from the index / navigation menu
* Cloud guides removed (U2F was the last guide, now deleted)
* WebAuthn access control guide
* Update access controls pages
Update links to WebAuthn and changes lingo to refer to either WebAuthn,
MFA, "second factor hardware token" and "second factor authenticator",
where appropriate.
U2F is moved to the references sections and WebAuthn is favored as the
guide to be followed in regards to MFA hardware tokens. Generic language
is used whenever possible, excluding places where we reference server
configuration or protocol support.
* WebAuthn cloud guide
* Update cloud pages
* WebAuthn config reference
* Update references to U2F in various pages
* Link to the WebAuthn guide in from the Authentication reference page
Incorporates ibeckermayer's suggestion from
https://github.com/gravitational/teleport/pull/8703.
* Rephrase sentences according to reviewer feedback
* Replace explicit <h2> with `##`
* Move "Migrating from U2F" section to the bottom
* Use numbered steps
* Include tabs for Cloud in config examples
* Add tctl as a prerequisite for WebAuthn setup
* Remove Cloud guides
U2F and WebAuthn were the last remaining items.
* Make linter happy
- Remove mentions of the "built in admin role" as we no longer create it
- Remove mentions to "beta" and use "preview" instead
- Add troubleshooting step for allowing DNS traffic
- Add a desktop access section to the main docs page
Fixes#8576
* Video Banner (#7914)
* Drain off admin guide into setup sections. (#7960)
* Expand daemon section and graceful restarts guide
* Move API section to top
* Move references to setup
Co-authored-by: Ben Arent <ben@goteleport.com>
* Open Sources Access Controls Docs (#6188)
Moves RBAC to a separate access controls section,
adds a couple of guides and prepares
the structure for more content.
* Fix href links
Paul Gottschling