change --board flag to --render-target

ci/release/changelogs/next.md

@@ -3,6 +3,7 @@
 - ELK now routes `sql_table` edges to the exact columns (ty @landmaj) [#1681](https://github.com/terrastruct/d2/pull/1681)
 - Adds new unfilled triangle arrowhead. [#1711](https://github.com/terrastruct/d2/pull/1711)
 - Grid containers can now have custom label positions. [#1715](https://github.com/terrastruct/d2/pull/1715)
+- A single board from a multi-board diagram can now be rendered with `--render-target` flag. [#1725](https://github.com/terrastruct/d2/pull/1725)
 
 #### Improvements 🧹
 

ci/release/template/man/d2.1

@@ -111,6 +111,9 @@ Bundle all assets and layers into the output svg
 .It Fl -force-appendix Ar false
 An appendix for tooltips and links is added to PNG exports since they are not interactive. Setting this to true adds an appendix to SVG exports as well
 .Ns .
+.It Fl -render-target
+Render a single board from multi-board diagram. E.g. root.scenarios.x to render only scenario x. If not provided, the entire diagram is rendered
+.Ns .
 .It Fl d , -debug
 Print debug logs
 .Ns .

d2cli/main.go

@@ -9,6 +9,7 @@ import (
 	"os/exec"
 	"os/user"
 	"path/filepath"
+	"regexp"
 	"strconv"
 	"strings"
 	"time"
@@ -47,6 +48,8 @@ import (
 	"cdr.dev/slog/sloggers/sloghuman"
 )
 
+var renderTargetPattern = regexp.MustCompile(`^root(\.\w+)*$`)
+
 func Run(ctx context.Context, ms *xmain.State) (err error) {
 	// :(
 	ctx = DiscardSlog(ctx)
@@ -114,7 +117,7 @@ func Run(ctx context.Context, ms *xmain.State) (err error) {
 	if err != nil {
 		return err
 	}
-	boardFlag := ms.Opts.String("D2_BOARD", "board", "", "", "render a single board from the diagram. E.g. root.scenarios.name to render scenario 'name'. If not provided, the entire diagram is rendered.")
+	renderTargetFlag := ms.Opts.String("", "render-target", "", "", "render a single board from multi-board diagram. E.g. root.scenarios.x to render only scenario x. If not provided, the entire diagram is rendered.")
 
 	fontRegularFlag := ms.Opts.String("D2_FONT_REGULAR", "font-regular", "", "", "path to .ttf file to use for the regular font. If none provided, Source Sans Pro Regular is used.")
 	fontItalicFlag := ms.Opts.String("D2_FONT_ITALIC", "font-italic", "", "", "path to .ttf file to use for the italic font. If none provided, Source Sans Pro Regular-Italic is used.")
@@ -261,11 +264,6 @@ func Run(ctx context.Context, ms *xmain.State) (err error) {
 			centerFlag = nil
 		}
 	}
-	if ms.Env.Getenv("D2_BOARD") == "" {
-		if _, ok := flagSet["board"]; !ok {
-			boardFlag = nil
-		}
-	}
 
 	if *darkThemeFlag == -1 {
 		darkThemeFlag = nil // TODO this is a temporary solution: https://github.com/terrastruct/util-go/issues/7
@@ -282,6 +280,15 @@ func Run(ctx context.Context, ms *xmain.State) (err error) {
 		scale = scaleFlag
 	}
 
+	switch *renderTargetFlag {
+	case "":
+		renderTargetFlag = nil
+	default:
+		if !renderTargetPattern.MatchString(*renderTargetFlag) {
+			return xmain.UsageErrorf("invalid --render-target: %s", *renderTargetFlag)
+		}
+	}
+
 	if !outputFormat.supportsDarkTheme() {
 		if darkThemeFlag != nil {
 			ms.Log.Warn.Printf("--dark-theme cannot be used while exporting to another format other than .svg")
@@ -315,8 +322,8 @@ func Run(ctx context.Context, ms *xmain.State) (err error) {
 		if inputPath == "-" {
 			return xmain.UsageErrorf("-w[atch] cannot be combined with reading input from stdin")
 		}
-		if boardFlag != nil {
-			return xmain.UsageErrorf("-w[atch] cannot be combined with -board")
+		if renderTargetFlag != nil {
+			return xmain.UsageErrorf("-w[atch] cannot be combined with --render-target")
 		}
 		w, err := newWatcher(ctx, ms, watcherOpts{
 			plugins:         plugins,
@@ -339,21 +346,17 @@ func Run(ctx context.Context, ms *xmain.State) (err error) {
 	}
 
 	var singleBoard bool
-	switch {
-	case boardFlag == nil:
-	case *boardFlag == "":
-		boardFlag = nil
-	default:
-		*boardFlag = strings.Replace(*boardFlag, ".", "/", -1)
-		*boardFlag = strings.TrimPrefix(*boardFlag, "root")
-		*boardFlag = strings.TrimPrefix(*boardFlag, "/")
+	if renderTargetFlag != nil {
+		*renderTargetFlag = strings.Replace(*renderTargetFlag, ".", "/", -1)
+		*renderTargetFlag = strings.TrimPrefix(*renderTargetFlag, "root")
+		*renderTargetFlag = strings.TrimPrefix(*renderTargetFlag, "/")
 		singleBoard = true
 	}
 
 	ctx, cancel := timelib.WithTimeout(ctx, time.Minute*2)
 	defer cancel()
 
-	_, written, err := compile(ctx, ms, plugins, layoutFlag, renderOpts, fontFamily, *animateIntervalFlag, inputPath, outputPath, boardFlag, singleBoard, *bundleFlag, *forceAppendixFlag, pw.Page)
+	_, written, err := compile(ctx, ms, plugins, layoutFlag, renderOpts, fontFamily, *animateIntervalFlag, inputPath, outputPath, renderTargetFlag, singleBoard, *bundleFlag, *forceAppendixFlag, pw.Page)
 	if err != nil {
 		if written {
 			return fmt.Errorf("failed to fully compile (partial render written) %s: %w", ms.HumanPath(inputPath), err)
@@ -422,7 +425,7 @@ func compile(ctx context.Context, ms *xmain.State, plugins []d2plugin.Plugin, la
 	if boardPath != nil {
 		diagram = diagram.GetBoard(*boardPath)
 		if diagram == nil {
-			return nil, false, fmt.Errorf(`board "%s" not found`, *boardPath)
+			return nil, false, fmt.Errorf(`render target "%s" not found`, *boardPath)
 		}
 		if singleBoard {
 			diagram.Name = ""

e2etests-cli/main_test.go

@@ -240,9 +240,9 @@ You provided: .png`)
 			},
 		},
 		{
-			name: "specific-board-root",
+			name: "render-target-root",
 			run: func(t *testing.T, ctx context.Context, dir string, env *xos.Env) {
-				writeFile(t, dir, "specific-board-root.d2", `direction: right
+				writeFile(t, dir, "render-target-root.d2", `direction: right
 title: {
 	label: Main Plan
 }
@@ -251,16 +251,16 @@ scenarios: {
 	title.label: Backup Plan
 	}
 }`)
-				err := runTestMain(t, ctx, dir, env, "--board=root", "specific-board-root.d2", "specific-board-root.svg")
+				err := runTestMain(t, ctx, dir, env, "--render-target=root", "render-target-root.d2", "render-target-root.svg")
 				assert.Success(t, err)
-				svg := readFile(t, dir, "specific-board-root.svg")
+				svg := readFile(t, dir, "render-target-root.svg")
 				assert.Testdata(t, ".svg", svg)
 			},
 		},
 		{
-			name: "specific-board-b",
+			name: "render-target-b",
 			run: func(t *testing.T, ctx context.Context, dir string, env *xos.Env) {
-				writeFile(t, dir, "specific-board-b.d2", `direction: right
+				writeFile(t, dir, "render-target-b.d2", `direction: right
 title: {
 	label: Main Plan
 }
@@ -269,18 +269,18 @@ scenarios: {
 	title.label: Backup Plan
 	}
 }`)
-				err := runTestMain(t, ctx, dir, env, "--board=root.b", "specific-board-b.d2", "specific-board-b.svg")
+				err := runTestMain(t, ctx, dir, env, "--render-target=root.b", "render-target-b.d2", "render-target-b.svg")
 				assert.Success(t, err)
-				svg := readFile(t, dir, "specific-board-b.svg")
+				svg := readFile(t, dir, "render-target-b.svg")
 				assert.Testdata(t, ".svg", svg)
 			},
 		},
 		{
-			name: "specific-board-invalid",
+			name: "render-target-invalid",
 			run: func(t *testing.T, ctx context.Context, dir string, env *xos.Env) {
-				writeFile(t, dir, "specific-board-invalid.d2", `x -> y`)
-				err := runTestMain(t, ctx, dir, env, "--board=b", "specific-board-invalid.d2", "specific-board-b.svg")
-				assert.ErrorString(t, err, `failed to wait xmain test: e2etests-cli/d2: failed to compile specific-board-invalid.d2: board "b" not found`)
+				writeFile(t, dir, "render-target-invalid.d2", `x -> y`)
+				err := runTestMain(t, ctx, dir, env, "--render-target=root.b", "render-target-invalid.d2", "render-target-invalid.svg")
+				assert.ErrorString(t, err, `failed to wait xmain test: e2etests-cli/d2: failed to compile render-target-invalid.d2: render target "b" not found`)
 			},
 		},
 		{