diff --git a/cmd/dagger/cmd/common/common.go b/cmd/dagger/cmd/common/common.go
index b2f2f847..29a8865a 100644
--- a/cmd/dagger/cmd/common/common.go
+++ b/cmd/dagger/cmd/common/common.go
@@ -122,8 +122,21 @@ func FormatValue(val *compiler.Value) string {
 	return strings.ReplaceAll(valStr, "\n", "\\n")
 }
 
-// ValueDocString returns the value doc from the comment lines
-func ValueDocString(val *compiler.Value) string {
+// ValueDocFull returns the full doc of the value
+func ValueDocFull(val *compiler.Value) string {
+	docs := []string{}
+	for _, c := range val.Doc() {
+		docs = append(docs, c.Text())
+	}
+	doc := strings.TrimSpace(strings.Join(docs, "\n"))
+	if len(doc) == 0 {
+		return "-"
+	}
+	return doc
+}
+
+// ValueDocOneLine returns the value doc as a single line
+func ValueDocOneLine(val *compiler.Value) string {
 	docs := []string{}
 	for _, c := range val.Doc() {
 		docs = append(docs, strings.TrimSpace(c.Text()))
diff --git a/cmd/dagger/cmd/doc.go b/cmd/dagger/cmd/doc.go
index 25560883..dcf111e4 100644
--- a/cmd/dagger/cmd/doc.go
+++ b/cmd/dagger/cmd/doc.go
@@ -107,7 +107,7 @@ func init() {
 }
 
 func mdEscape(s string) string {
-	escape := []string{"|", "<", ">"}
+	escape := []string{"<", ">"}
 	for _, c := range escape {
 		s = strings.ReplaceAll(s, c, `\`+c)
 	}
@@ -151,7 +151,7 @@ func loadCode(packageName string) (*compiler.Value, error) {
 func printValuesText(iw io.Writer, libName string, values []*compiler.Value) {
 	w := tabwriter.NewWriter(iw, 0, 4, len(textPadding), ' ', 0)
 	for _, i := range values {
-		docStr := terminalTrim(common.ValueDocString(i))
+		docStr := terminalTrim(common.ValueDocOneLine(i))
 		fmt.Fprintf(w, "\t\t%s\t%s\t%s\n",
 			formatLabel(libName, i), common.FormatValue(i), docStr)
 	}
@@ -167,9 +167,8 @@ func printValuesMarkdown(iw io.Writer, libName string, values []*compiler.Value)
 		fmt.Fprintf(w, "|*%s*\t|``%s``\t|%s\t|\n",
 			formatLabel(libName, i),
 			mdEscape(common.FormatValue(i)),
-			mdEscape(common.ValueDocString(i)))
+			mdEscape(common.ValueDocOneLine(i)))
 	}
-	fmt.Fprintln(w)
 	w.Flush()
 }
 
@@ -181,7 +180,7 @@ func valuesToJSON(libName string, values []*compiler.Value) []ValueJSON {
 		v := ValueJSON{}
 		v.Name = formatLabel(libName, i)
 		v.Type = common.FormatValue(i)
-		v.Description = common.ValueDocString(i)
+		v.Description = common.ValueDocOneLine(i)
 		val = append(val, v)
 	}
 
@@ -201,18 +200,17 @@ func PrintDoc(ctx context.Context, w io.Writer, packageName string, val *compile
 	switch format {
 	case textFormat:
 		fmt.Fprintf(w, "Package %s\n", packageName)
-		fmt.Fprintf(w, "\n%s\n", common.ValueDocString(val))
+		fmt.Fprintf(w, "\n%s\n", common.ValueDocFull(val))
 	case markdownFormat:
-		fmt.Fprintf(w, "## Package %s\n", mdEscape(packageName))
-		comment := common.ValueDocString(val)
+		fmt.Fprintf(w, "# Package %s\n", mdEscape(packageName))
+		comment := common.ValueDocFull(val)
 		if comment == "-" {
-			fmt.Println()
 			break
 		}
-		fmt.Fprintf(w, "\n%s\n\n", mdEscape(comment))
+		fmt.Fprintf(w, "\n%s\n", mdEscape(comment))
 	case jsonFormat:
 		packageJSON.Name = packageName
-		comment := common.ValueDocString(val)
+		comment := common.ValueDocFull(val)
 		if comment != "-" {
 			packageJSON.Description = comment
 		}
@@ -235,18 +233,18 @@ func PrintDoc(ctx context.Context, w io.Writer, packageName string, val *compile
 		}
 
 		// Field Name + Description
-		comment := common.ValueDocString(v)
+		comment := common.ValueDocOneLine(v)
 		switch format {
 		case textFormat:
 			fmt.Fprintf(w, "\n%s\n\n%s%s\n", name, textPadding, comment)
 		case markdownFormat:
-			fmt.Fprintf(w, "### %s\n\n", name)
+			fmt.Fprintf(w, "\n## %s\n\n", name)
 			if comment != "-" {
 				fmt.Fprintf(w, "%s\n\n", mdEscape(comment))
 			}
 		case jsonFormat:
 			fieldJSON.Name = name
-			comment := common.ValueDocString(val)
+			comment := common.ValueDocOneLine(val)
 			if comment != "-" {
 				fieldJSON.Description = comment
 			}
@@ -263,9 +261,9 @@ func PrintDoc(ctx context.Context, w io.Writer, packageName string, val *compile
 			fmt.Fprintf(w, "\n%sInputs:\n", textPadding)
 			printValuesText(w, name, inp)
 		case markdownFormat:
-			fmt.Fprintf(w, "#### %s Inputs\n\n", mdEscape(name))
+			fmt.Fprintf(w, "### %s Inputs\n\n", mdEscape(name))
 			if len(inp) == 0 {
-				fmt.Fprintf(w, "_No input._\n\n")
+				fmt.Fprintf(w, "_No input._\n")
 				break
 			}
 			printValuesMarkdown(w, name, inp)
@@ -284,9 +282,9 @@ func PrintDoc(ctx context.Context, w io.Writer, packageName string, val *compile
 			fmt.Fprintf(w, "\n%sOutputs:\n", textPadding)
 			printValuesText(w, name, out)
 		case markdownFormat:
-			fmt.Fprintf(w, "#### %s Outputs\n\n", mdEscape(name))
+			fmt.Fprintf(w, "\n### %s Outputs\n\n", mdEscape(name))
 			if len(out) == 0 {
-				fmt.Fprintf(w, "_No output._\n\n")
+				fmt.Fprintf(w, "_No output._\n")
 				break
 			}
 			printValuesMarkdown(w, name, out)
diff --git a/cmd/dagger/cmd/input/list.go b/cmd/dagger/cmd/input/list.go
index 0d97d0f4..2df921ed 100644
--- a/cmd/dagger/cmd/input/list.go
+++ b/cmd/dagger/cmd/input/list.go
@@ -69,7 +69,7 @@ var listCmd = &cobra.Command{
 					inp.Path(),
 					common.FormatValue(inp),
 					isUserSet(st, inp),
-					common.ValueDocString(inp),
+					common.ValueDocOneLine(inp),
 				)
 			}
 
diff --git a/cmd/dagger/cmd/output/list.go b/cmd/dagger/cmd/output/list.go
index 502d7b10..983becc8 100644
--- a/cmd/dagger/cmd/output/list.go
+++ b/cmd/dagger/cmd/output/list.go
@@ -72,7 +72,7 @@ func ListOutputs(ctx context.Context, st *state.State, isTTY bool) {
 			fmt.Fprintf(w, "%s\t%s\t%s\n",
 				out.Path(),
 				common.FormatValue(out),
-				common.ValueDocString(out),
+				common.ValueDocOneLine(out),
 			)
 		}