diff --git a/.github/workflows/markdown.links.config.json b/.github/workflows/markdown.links.config.json
index 1c42ecb1d4bf..28863d7bdd71 100644
--- a/.github/workflows/markdown.links.config.json
+++ b/.github/workflows/markdown.links.config.json
@@ -1,5 +1,8 @@
{
"ignorePatterns": [
+ {
+ "pattern": "^https://github.com/grafana/agent/pull/XXXX$"
+ },
{
"pattern": "^http://prometheus.k3d.localhost:30080"
},
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index dc164698cd2a..ac94e4297517 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -5,7 +5,7 @@ on:
branches:
- main
paths:
- - 'docs/**'
+ - 'docs/user/**'
jobs:
sync:
@@ -21,7 +21,7 @@ jobs:
branch: master
host: github.com
github_pat: '${{ secrets.GH_BOT_ACCESS_TOKEN }}'
- source_folder: docs
+ source_folder: docs/user
target_folder: content/docs/agent/latest
- shell: bash
run: |
diff --git a/docs/README.md b/docs/README.md
index 51c262484e4c..88efe6babd4f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,21 +1,10 @@
-+++
-draft = "True"
-+++
+# Grafana Agent Documentation
-
+This directory contains documentation for Grafana Agent. It is split into two
+parts:
-Grafana Agent is an telemetry collector for sending metrics, logs,
-and trace data to the opinionated Grafana observability stack. It works best
-with:
-
-* [Grafana Cloud](https://grafana.com/products/cloud/)
-* [Grafana Enterprise Stack](https://grafana.com/products/enterprise/)
-* OSS deployments of [Grafana Loki](https://grafana.com/oss/loki/), [Prometheus](https://prometheus.io/), [Cortex](https://cortexmetrics.io/), and [Grafana Tempo](https://grafana.com/oss/tempo/)
-
-
-- Grafana Agent uses less memory on average than Prometheus – by doing less
- (only focusing on `remote_write`-related functionality).
-- Grafana Agent allows for deploying multiple instances of the Agent in a
- cluster and only scraping metrics from targets that are running on the same host.
- This allows for distributing memory requirements across the cluster
- rather than pressurizing a single node.
+* `user/`: Documentation for users. This directory is hosted on
+ [grafana.com/docs/agent](https://grafana.com/docs/agent/latest/) and we
+ recommend interacting with it there instead of viewing the markdown on
+ Github.
+* `rfcs/`: RFCs for proposals relating to Grafana Agent.
diff --git a/docs/rfcs/0000-template.md b/docs/rfcs/0000-template.md
new file mode 100644
index 000000000000..c565ea04e584
--- /dev/null
+++ b/docs/rfcs/0000-template.md
@@ -0,0 +1,5 @@
+# Title
+
+* Date: YYYY-MM-DD
+* Author: Full Name (@github_username)
+* PR: [grafana/agent#XXXX](https://github.com/grafana/agent/pull/XXXX)
diff --git a/docs/rfcs/0001-designing-in-the-open.md b/docs/rfcs/0001-designing-in-the-open.md
new file mode 100644
index 000000000000..08ba5e030aa3
--- /dev/null
+++ b/docs/rfcs/0001-designing-in-the-open.md
@@ -0,0 +1,141 @@
+# Designing in the Open
+
+* Date: 2021-11-02
+* Author: Robert Fratto (@rfratto)
+* PR: [grafana/agent#1055](https://github.com/grafana/agent/pull/1055)
+
+## Summary
+
+Many open source projects start behind closed doors, where it's designed,
+prototyped, and tested before being released publicly. This can be true
+regardless of why the project is being made; even personal side projects likely
+start by someone designing alone.
+
+Meanwhile, many open source projects might want to create a community of
+developers. Much of the beauty of succesful open source projects originates
+from the varied backgrounds of its contributors: different people with
+different use cases combining together to make a widely useful piece of
+software.
+
+However, even with an intent to foster a community of developers, it's natural
+to accidentally build a habit from the closed-door design process. Even when
+once-private proposals are made public, potential external contributors can
+find themselves simply as spectators:
+
+* Initial design is gated to core maintainers, in particular if they all work
+ for the same company. This leaves less room for new people to help out.
+* New concerns are less impactful if the proposal already receieved core
+ maintainer consensus.
+* Historical proposals with context and discussions become hard to find.
+
+I believe it takes a deliberate inversion of process to foster community
+participation. This document proposes how Grafana Agent will utilize public
+spaces for its primary home for future design proposals.
+
+## Goals
+
+* Outline options for proposing changes to Grafana Agent
+* Lower the barrier to entry for interested parties to become maintainers
+
+## Non-Goals
+
+* Enforce that every change originates from a fully public proposal or
+ discussion. While all maintainers and contributors will be encouraged to
+ design openly, there may be legal, security, privacy, or business reasons
+ that prevent some or all context from being made public.
+
+* Be overly prescriptive: too many rules can hinder adoption of a process. This
+ document outlines intention, not hard policy.
+
+## Proposal
+
+Public proposals may take one of two forms:
+
+* Issue proposals
+* RFC PR proposals (e.g., this document)
+
+### Issues
+
+Issues are the quickest path towards proposing a change. Issue proposals must
+be opened at the [grafana/agent issues page](https://github.com/grafana/agent/issues).
+
+There are no strict set of rules for issue-based proposals, but authors are
+recommended to prefix the issue title with `Proposal:` so it may be found more
+easily.
+
+### RFC PRs
+
+RFC PR proposals must at least:
+
+* Be placed in the `docs/rfcs` folder of the `grafana/agent` repository
+* Have a lowercase filename in hyphen-case with an `.md` extension
+* Prefix the filename with the RFC ID
+ * ID `xxxx` may be initially used until the final ID is known
+* Contain valid markdown
+* Start with the title of the proposal
+* Contain a bullet point list of metadata of:
+ * The date the proposal was written
+ * The list of authors, with their names and GitHub usernames
+ * The PR where the proposal was posted
+
+`0000-template.md` contains a template to use for writing proposals that
+conforms to these rules.
+
+The remainder of the proposal may be formatted however the author wishes. Some
+example sections in the RFC may be:
+
+* Summary: What is the background that lead to this proposal?
+* Goals: What are the main goals of the proposal?
+* Non-Goals: What _aren't_ the main goals of the proposal?
+* Proposal: What is the proposal?
+* Pros/Cons:
+ * Pros: What are the upsides to this proposal?
+ * Cons: What are the downsides to this proposal?
+* Considered Alternatives: Why is this proposal the best path forward? What
+ were the alternatives?
+* Open Questions: What questions still need to be answered?
+* Prior Art: What was this proposal based on, if anything?
+
+#### RFC Review
+
+RFCs should be opened as a PR to grafana/agent, ideally prefixed in the PR
+title with `RFC:` to easily identify it amongst other PRs.
+
+### Google Docs Proposals
+
+Google Docs may be useful for early feedback rounds during a proposal. However,
+it is not recommended for the permanent home of a proposal:
+
+* Change and comment history may not be available to all viewers.
+
+* The file owner may delete the proposal, leading to a gap in historical
+ context.
+
+Google Docs proposals will be permitted if linked to from an issue proposal.
+Google Doc proposals must be converted into an RFC proposal prior to formally
+accepting the proposal. Enforcing this ensures that historical context is
+recorded, though it is still not ideal as it discards comment history.
+
+## Accepting Proposals
+
+All readers are encouraged to engage in reviewing proposals. However, whether a
+proposal is accepted is determined by [rough consensus][] of the Grafana Agent
+governance team. External contributors may eventually be invited to [join the
+governance team][governance] if they have a history of making ongoing
+contributions to the project or community.
+
+## Considered alternatives
+
+A few existing public proposal processes have been examined for inspiration:
+
+* [IETF's RFCs](https://www.ietf.org/standards/rfcs/)
+* [Rust's RFCs](https://github.com/rust-lang/rfcs)
+* [Joyent's Requests for Discussions](https://github.com/joyent/rfd)
+* [OpenTelemetry's OTEPs](https://github.com/open-telemetry/oteps)
+* [Kubernetes Enhancement Proposals (KEPs)](https://github.com/kubernetes/enhancements)
+
+All of these processes are similar, but in the end, the current objective is to
+start collecting proposals publicly rather than to be prescriptive yet.
+
+[rough consensus]: https://github.com/grafana/agent/blob/main/GOVERNANCE.md#technical-decisions
+[governance]: https://github.com/grafana/agent/blob/main/GOVERNANCE.md#team-members
diff --git a/docs/user/README.md b/docs/user/README.md
new file mode 100644
index 000000000000..51c262484e4c
--- /dev/null
+++ b/docs/user/README.md
@@ -0,0 +1,21 @@
++++
+draft = "True"
++++
+
+
+
+Grafana Agent is an telemetry collector for sending metrics, logs,
+and trace data to the opinionated Grafana observability stack. It works best
+with:
+
+* [Grafana Cloud](https://grafana.com/products/cloud/)
+* [Grafana Enterprise Stack](https://grafana.com/products/enterprise/)
+* OSS deployments of [Grafana Loki](https://grafana.com/oss/loki/), [Prometheus](https://prometheus.io/), [Cortex](https://cortexmetrics.io/), and [Grafana Tempo](https://grafana.com/oss/tempo/)
+
+
+- Grafana Agent uses less memory on average than Prometheus – by doing less
+ (only focusing on `remote_write`-related functionality).
+- Grafana Agent allows for deploying multiple instances of the Agent in a
+ cluster and only scraping metrics from targets that are running on the same host.
+ This allows for distributing memory requirements across the cluster
+ rather than pressurizing a single node.
diff --git a/docs/_index.md b/docs/user/_index.md
similarity index 100%
rename from docs/_index.md
rename to docs/user/_index.md
diff --git a/docs/api/_index.md b/docs/user/api/_index.md
similarity index 100%
rename from docs/api/_index.md
rename to docs/user/api/_index.md
diff --git a/docs/assets/logo_and_name.png b/docs/user/assets/logo_and_name.png
similarity index 100%
rename from docs/assets/logo_and_name.png
rename to docs/user/assets/logo_and_name.png
diff --git a/docs/configuration/_index.md b/docs/user/configuration/_index.md
similarity index 100%
rename from docs/configuration/_index.md
rename to docs/user/configuration/_index.md
diff --git a/docs/configuration/integrations/_index.md b/docs/user/configuration/integrations/_index.md
similarity index 100%
rename from docs/configuration/integrations/_index.md
rename to docs/user/configuration/integrations/_index.md
diff --git a/docs/configuration/integrations/cadvisor-config.md b/docs/user/configuration/integrations/cadvisor-config.md
similarity index 100%
rename from docs/configuration/integrations/cadvisor-config.md
rename to docs/user/configuration/integrations/cadvisor-config.md
diff --git a/docs/configuration/integrations/consul-exporter-config.md b/docs/user/configuration/integrations/consul-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/consul-exporter-config.md
rename to docs/user/configuration/integrations/consul-exporter-config.md
diff --git a/docs/configuration/integrations/dnsmasq-exporter-config.md b/docs/user/configuration/integrations/dnsmasq-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/dnsmasq-exporter-config.md
rename to docs/user/configuration/integrations/dnsmasq-exporter-config.md
diff --git a/docs/configuration/integrations/elasticsearch-exporter-config.md b/docs/user/configuration/integrations/elasticsearch-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/elasticsearch-exporter-config.md
rename to docs/user/configuration/integrations/elasticsearch-exporter-config.md
diff --git a/docs/configuration/integrations/github-exporter-config.md b/docs/user/configuration/integrations/github-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/github-exporter-config.md
rename to docs/user/configuration/integrations/github-exporter-config.md
diff --git a/docs/configuration/integrations/integrations-next/_index.md b/docs/user/configuration/integrations/integrations-next/_index.md
similarity index 100%
rename from docs/configuration/integrations/integrations-next/_index.md
rename to docs/user/configuration/integrations/integrations-next/_index.md
diff --git a/docs/configuration/integrations/integrations-next/eventhandler-config.md b/docs/user/configuration/integrations/integrations-next/eventhandler-config.md
similarity index 100%
rename from docs/configuration/integrations/integrations-next/eventhandler-config.md
rename to docs/user/configuration/integrations/integrations-next/eventhandler-config.md
diff --git a/docs/configuration/integrations/kafka-exporter-config.md b/docs/user/configuration/integrations/kafka-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/kafka-exporter-config.md
rename to docs/user/configuration/integrations/kafka-exporter-config.md
diff --git a/docs/configuration/integrations/memcached-exporter-config.md b/docs/user/configuration/integrations/memcached-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/memcached-exporter-config.md
rename to docs/user/configuration/integrations/memcached-exporter-config.md
diff --git a/docs/configuration/integrations/mongodb_exporter-config.md b/docs/user/configuration/integrations/mongodb_exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/mongodb_exporter-config.md
rename to docs/user/configuration/integrations/mongodb_exporter-config.md
diff --git a/docs/configuration/integrations/mysqld-exporter-config.md b/docs/user/configuration/integrations/mysqld-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/mysqld-exporter-config.md
rename to docs/user/configuration/integrations/mysqld-exporter-config.md
diff --git a/docs/configuration/integrations/node-exporter-config.md b/docs/user/configuration/integrations/node-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/node-exporter-config.md
rename to docs/user/configuration/integrations/node-exporter-config.md
diff --git a/docs/configuration/integrations/postgres-exporter-config.md b/docs/user/configuration/integrations/postgres-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/postgres-exporter-config.md
rename to docs/user/configuration/integrations/postgres-exporter-config.md
diff --git a/docs/configuration/integrations/process-exporter-config.md b/docs/user/configuration/integrations/process-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/process-exporter-config.md
rename to docs/user/configuration/integrations/process-exporter-config.md
diff --git a/docs/configuration/integrations/redis-exporter-config.md b/docs/user/configuration/integrations/redis-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/redis-exporter-config.md
rename to docs/user/configuration/integrations/redis-exporter-config.md
diff --git a/docs/configuration/integrations/statsd-exporter-config.md b/docs/user/configuration/integrations/statsd-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/statsd-exporter-config.md
rename to docs/user/configuration/integrations/statsd-exporter-config.md
diff --git a/docs/configuration/integrations/windows-exporter-config.md b/docs/user/configuration/integrations/windows-exporter-config.md
similarity index 100%
rename from docs/configuration/integrations/windows-exporter-config.md
rename to docs/user/configuration/integrations/windows-exporter-config.md
diff --git a/docs/configuration/logs-config.md b/docs/user/configuration/logs-config.md
similarity index 100%
rename from docs/configuration/logs-config.md
rename to docs/user/configuration/logs-config.md
diff --git a/docs/configuration/metrics-config.md b/docs/user/configuration/metrics-config.md
similarity index 100%
rename from docs/configuration/metrics-config.md
rename to docs/user/configuration/metrics-config.md
diff --git a/docs/configuration/server-config.md b/docs/user/configuration/server-config.md
similarity index 100%
rename from docs/configuration/server-config.md
rename to docs/user/configuration/server-config.md
diff --git a/docs/configuration/traces-config.md b/docs/user/configuration/traces-config.md
similarity index 100%
rename from docs/configuration/traces-config.md
rename to docs/user/configuration/traces-config.md
diff --git a/docs/getting-started/_index.md b/docs/user/getting-started/_index.md
similarity index 100%
rename from docs/getting-started/_index.md
rename to docs/user/getting-started/_index.md
diff --git a/docs/getting-started/create-config-file.md b/docs/user/getting-started/create-config-file.md
similarity index 100%
rename from docs/getting-started/create-config-file.md
rename to docs/user/getting-started/create-config-file.md
diff --git a/docs/getting-started/install-agent-on-windows.md b/docs/user/getting-started/install-agent-on-windows.md
similarity index 100%
rename from docs/getting-started/install-agent-on-windows.md
rename to docs/user/getting-started/install-agent-on-windows.md
diff --git a/docs/operation-guide/_index.md b/docs/user/operation-guide/_index.md
similarity index 100%
rename from docs/operation-guide/_index.md
rename to docs/user/operation-guide/_index.md
diff --git a/docs/operator/_index.md b/docs/user/operator/_index.md
similarity index 100%
rename from docs/operator/_index.md
rename to docs/user/operator/_index.md
diff --git a/docs/operator/add-custom-scrape-jobs.md b/docs/user/operator/add-custom-scrape-jobs.md
similarity index 100%
rename from docs/operator/add-custom-scrape-jobs.md
rename to docs/user/operator/add-custom-scrape-jobs.md
diff --git a/docs/operator/architecture.md b/docs/user/operator/architecture.md
similarity index 100%
rename from docs/operator/architecture.md
rename to docs/user/operator/architecture.md
diff --git a/docs/operator/custom-resource-quickstart.md b/docs/user/operator/custom-resource-quickstart.md
similarity index 100%
rename from docs/operator/custom-resource-quickstart.md
rename to docs/user/operator/custom-resource-quickstart.md
diff --git a/docs/operator/getting-started.md b/docs/user/operator/getting-started.md
similarity index 100%
rename from docs/operator/getting-started.md
rename to docs/user/operator/getting-started.md
diff --git a/docs/operator/helm-getting-started.md b/docs/user/operator/helm-getting-started.md
similarity index 100%
rename from docs/operator/helm-getting-started.md
rename to docs/user/operator/helm-getting-started.md
diff --git a/docs/scraping-service/_index.md b/docs/user/scraping-service/_index.md
similarity index 100%
rename from docs/scraping-service/_index.md
rename to docs/user/scraping-service/_index.md
diff --git a/docs/upgrade-guide/_index.md b/docs/user/upgrade-guide/_index.md
similarity index 100%
rename from docs/upgrade-guide/_index.md
rename to docs/user/upgrade-guide/_index.md
diff --git a/production/README.md b/production/README.md
index 554ce6ca580f..a73aca24a288 100644
--- a/production/README.md
+++ b/production/README.md
@@ -13,7 +13,7 @@ Here are some resources to help you run the Grafana Agent:
## Windows Installation
-To run the Windows Installation, download the Windows Installer executable from the [release page](https://github.com/grafana/agent/releases). Then run the installer, this will setup the Agent and run the Agent as a Windows Service. More details can be found in the [Windows Guide](../docs/getting-started/install-agent-on-windows.md)
+To run the Windows Installation, download the Windows Installer executable from the [release page](https://github.com/grafana/agent/releases). Then run the installer, this will setup the Agent and run the Agent as a Windows Service. More details can be found in the [Windows Guide](https://grafana.com/docs/agent/latest/getting-started/install-agent-on-windows/)
## Running the Agent with Docker