Restructure site/ directory into docs/ which only contains Bazel documentation.
The new docs/ directory in the bazel source tree will only contain the Bazel
docs site, which is hosted at docs.bazel.build. This change deletes the
marketing site and blog, which have been migrated to the bazel-website and
bazel-blog GitHub repositories respectively.
This change also updates the serve-docs.sh and ci/build.sh under scripts/ in
preparation for publishing the docs site.
Note that to help make reviews more manageable, this change is limited to
moving files to their new locations. Here are the follow-up changes:
* Update all links in docs to remove versions/master in paths and to add
correct bazel.build subdomain when linking to pages on the marketing site
or the blog.
* Set up versioned directories on GCS bucket and add tooling for versioning
docs
This change is also coordinated with
https://bazel-review.googlesource.com/c/11568/ to have the PublishSite job
publish to docs.bazel.build rather than www.bazel.build.
Issue #2397
RELNOTES: None
PiperOrigin-RevId: 157612651
diff --git a/site/docs/getting-started.md b/site/docs/getting-started.md
index 1e69dce..66a87e4 100644
--- a/site/docs/getting-started.md
+++ b/site/docs/getting-started.md
@@ -1,4 +1,97 @@
---
-layout: redirect
-redirect: docs/getting-started.html
+layout: documentation
+title: Getting Started
---
+
+# Getting Started with Bazel
+
+## Setup
+
+Use the [installation instructions](/docs/install.html) to install a copy of
+Bazel on your machine.
+
+## Using a Workspace
+
+All Bazel builds take place in a [_workspace_](/docs/build-ref.html#workspaces),
+a directory on your filesystem that contains source code for the software you
+want to build, as well symbolic links to directories that contain the build
+outputs (for example, `bazel-bin` and `bazel-out`). The location of the
+workspace directory is not significant, but it must contain a file called
+`WORKSPACE` in the top-level directory; an empty file is a valid workspace.
+The `WORKSPACE` file can be used to reference
+[external dependencies](/docs/external.html) required to build the outputs.
+One workspace can be shared among multiple projects if desired.
+
+```bash
+touch WORKSPACE
+```
+
+## Creating a Build File
+
+To know which targets can be built in your project, Bazel inspects `BUILD`
+files. They are written in Bazel's build language which is syntactically
+similar to Python. Usually they are just a sequence of declarations of rules.
+Each rule specifies its inputs, outputs, and a way to compute the outputs from
+the inputs.
+
+The rule probably most familiar to people who have used `Makefile`s before (as
+it is the only rule available there) is the
+[genrule](/docs/be/general.html#genrule), which specifies how the output can
+be generated by invoking a shell command.
+
+```
+genrule(
+ name = "hello",
+ outs = ["hello_world.txt"],
+ cmd = "echo Hello World > $@",
+)
+```
+
+The shell command may contain [Make variables](/docs/be/make-variables.html).
+
+Using the above `BUILD` file, you can ask Bazel to generate the target.
+
+```
+$ bazel build :hello
+.
+INFO: Found 1 target...
+Target //:hello up-to-date:
+ bazel-genfiles/hello_world.txt
+INFO: Elapsed time: 2.255s, Critical Path: 0.07s
+```
+
+We note two things. First, targets are normally referred to by their
+[label](/docs/build-ref.html#labels), which is specified by the
+[name](/docs/be/general.html#genrule.name) attribute of the rule. (Referencing
+them by the output file name is also possible, but this is not the preferred
+way.) Second, Bazel puts the generated files into a separate directory (the
+`bazel-genfiles` directory is actually a symbolic link) so as not to pollute
+your source tree.
+
+Rules may use the output of other rules as input, as in the following
+example. Again, the generated sources are referred to by their label.
+
+```
+genrule(
+ name = "hello",
+ outs = ["hello_world.txt"],
+ cmd = "echo Hello World > $@",
+)
+
+genrule(
+ name = "double",
+ srcs = [":hello"],
+ outs = ["double_hello.txt"],
+ cmd = "cat $< $< > $@",
+)
+```
+
+Finally, note that, while the [genrule](/docs/be/general.html#genrule) might
+seem familiar, it usually is _not_ the best rule to use. It is preferrable to
+use one of the specialized [rules](/docs/be/overview.html#rules) for various
+languages.
+
+# Next Steps
+
+Next, check out the tutorial on building [Java](/docs/tutorial/java.html)
+or [C++](/docs/tutorial/cpp.html) programs.
