From c4eed04483deccc2292048f3bc78629b7a83f00e Mon Sep 17 00:00:00 2001
From: Georgi Matev <georgi.matev@gmail.com>
Date: Thu, 6 Oct 2022 10:57:32 -0700
Subject: [PATCH] Fill in developer/build.md page placeholder (#1065)

## Description

* Fill in developer/build.md page placeholder
* Fix some liniting issues

## Type of change

<!--- Please check the type of change your PR introduces: --->
- [ ] :sunflower: Feature
- [ ] :bug: Bugfix
- [x] :world_map: Documentation
- [ ] :robot: Test
- [ ] :computer: CI/Deployment
- [ ] :hamster: Trivial/Minor

## Issue(s)

<!-- Can reference multiple issues. Use one of the following "magic words" - "closes, fixes" to auto-close the Github issue. -->

## Test Plan

<!-- How will this be tested prior to merging.-->
- [x] :muscle: Manual
- [ ] :zap: Unit test
- [ ] :green_heart: E2E
---
 README.md                     | 28 +++++++++++-----------------
 docs/docs/developers/build.md | 23 +++++++++++++++++++----
 src/cmd/mdgen/mdgen.go        |  8 +++++---
 3 files changed, 35 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index df3b23232..9e6cd2144 100644
--- a/README.md
+++ b/README.md
@@ -16,33 +16,27 @@ As Corso evolves, it can become a great building block for more complex data pro
 Corso supports M365 Exchange and OneDrive with SharePoint and Teams support in active development. Coverage for more
 services, possibly beyond M365, will expand based on the interest and needs of the community.
 
-## Getting Started
+# Getting Started
 
-TODO - Link to the appropriate page in the published docs.
+See the [Corso Documentation](https://docs.corsobackup.io) for more information.
 
-## Building Corso
+# Corso container images
+
+Corso container images are convenienty hosted on [ghrc.io](https://github.com/alcionai/corso/pkgs/container/corso).
+
+For a sepcific release, use the following command:
 
 ```sh
-# Build a binary. Will be placed in bin/
-./build/build.sh 
-
-# Build a container image
-./build/build-container.sh 
+docker pull ghcr.io/alcionai/corso:<release tag>
 ```
 
-# Containers
+# Building Corso
 
-Corso images are hosted on [ghrc.io](https://github.com/alcionai/corso/pkgs/container/corso).
-
-Rolling release
-```sh
-docker pull ghcr.io/alcionai/corso:{SHA} --platform linux/arm64
-```
+To learn more about working with the project source core and building Corso, see the
+[Developer section](https://docs.corsobackup.io/developers/build) of the Corso Documentation.
 
 # Contribution Guidelines
 
-TODO 
-
 ## Code of Conduct
 
 It's important that our community is inclusive and respectful of everyone.
diff --git a/docs/docs/developers/build.md b/docs/docs/developers/build.md
index 79bdfc55d..d697b98a7 100644
--- a/docs/docs/developers/build.md
+++ b/docs/docs/developers/build.md
@@ -1,5 +1,20 @@
-# Build from source
+# Building Corso
 
-<!-- vale proselint.Annotations = NO -->
-TODO
-<!-- vale proselint.Annotations = YES -->
+For convenience, the Corso build tooling is containerized. To take advantage, you need
+[Docker](https://www.docker.com/) installed on your machine.
+
+To build Corso locally, use the following command from the root of your repo:
+
+```bash
+./build/build.sh 
+
+```
+
+The resulting binary will be under `<repo root>/bin`
+
+If you prefer to build Corso as a container, use the following command:
+
+```bash
+# Use --help to see all available options
+./build/build-container.sh 
+```
diff --git a/src/cmd/mdgen/mdgen.go b/src/cmd/mdgen/mdgen.go
index 3cc0020db..9534491e0 100644
--- a/src/cmd/mdgen/mdgen.go
+++ b/src/cmd/mdgen/mdgen.go
@@ -132,16 +132,18 @@ func genMarkdownCustomCorso(cmd *cobra.Command, w io.Writer) error {
 	buf.WriteString("## " + name + "\n\n")
 
 	if len(cmd.Long) > 0 {
-		buf.WriteString(cmd.Long + "\n\n")
+		buf.WriteString(cmd.Long + "\n")
 	} else {
-		buf.WriteString(cmd.Short + "\n\n")
+		buf.WriteString(cmd.Short + "\n")
 	}
 
 	if cmd.Runnable() {
-		buf.WriteString(fmt.Sprintf("```bash\n%s\n```\n\n", cmd.UseLine()))
+		buf.WriteString("\n")
+		buf.WriteString(fmt.Sprintf("```bash\n%s\n```\n", cmd.UseLine()))
 	}
 
 	if cmd.HasExample() {
+		buf.WriteString("\n")
 		buf.WriteString("### Examples\n\n")
 		buf.WriteString(fmt.Sprintf("```bash\n%s\n```\n", cmd.Example))
 	}