allow passing arbitrary options

d2/config.py

@@ -28,7 +28,7 @@ def d2_config(self):
         return _dict
 
 
-class D2Config(BaseModel, extra="forbid"):
+class D2Config(BaseModel, extra="allow"):
     layout: str
     theme: int
     dark_theme: int
@@ -50,4 +50,8 @@ def opts(self) -> List[str]:
             f"--target={self.target}",
         ]
 
+        if extra := self.model_extra:
+            for k, v in extra.items():
+                opts += [f"--{k.replace('_', '-')}={v}"]
+
         return opts

docs/docs/guide/configuration.md

@@ -44,7 +44,28 @@ You can override locally everything except:
 * `cache`
 * `cache_dir`
 
-### Fenced code blocks
+You can use local configuration to set options which are
+not explicitly provided by the plugin, for example
+[layout engine specific options](https://d2lang.com/tour/layouts/#layout-engines).
+
+These options are not validated and passed directly to the d2 after some basic
+preprocessing. Expect d2 errors if you provide invalid options.
+
+As an example, to pass this option:
+
+```bash
+--elk-nodeSelfLoop int      spacing to be preserved between a node and its self loops
+```
+
+Specify it like this (notice `_` instead of `-`):
+
+````md
+```d2 elk_nodeSelfLoop="10"
+self -> other
+```
+````
+
+## Fenced code blocks
 
 Configuration options are specified as key="value" pairs after the
 language tag.
@@ -64,9 +85,9 @@ There is one special option, `render="False"`, available only in fenced code blo
 This option disables rendering of the diagram and allows you to display
 the diagram definition instead.
 
-#### Examples
+### Examples
 
-##### Padding and scale
+#### Padding and scale
 
 ````md
 ```d2 pad="20" scale="0.7"
@@ -86,7 +107,7 @@ John.ack -> Alice: Hi Alice, I can hear you!
 John -> Alice: I feel great!
 ```
 
-##### Disabled rendering
+#### Disabled rendering
 
 ````md
 ```d2 render="False"
@@ -98,7 +119,7 @@ Bob -> Alice
 Bob -> Alice
 ```
 
-##### Rendering specific target
+#### Rendering specific target
 
 ````md
 ```d2 pad="10" scale="1" target="alternative"
@@ -126,7 +147,7 @@ scenarios: {
 }
 ```
 
-### Image tags
+## Image tags
 
 Image tags use [attr_list](https://python-markdown.github.io/extensions/attr_list/)
 extension to specify configuration options.
@@ -139,17 +160,17 @@ Contrary to fenced code blocks, quotes around values are optional. However
 **white space before opening brace is not allowed**. Add space and you will
 se no error but the diagram will be rendered with global configuration only.
 
-#### Examples
+### Examples
 
-##### Theme and layout
+#### Theme and layout
 
 ```md
 ![Cloud](cloud.d2){theme=101 layout=elk}
 ```
 
 ![Cloud](cloud.d2){theme=101 layout=elk}
 
-##### Dark theme
+#### Dark theme
 
 ```md
 ![Cloud](cloud.d2){dark_theme="201"}

docs/requirements.txt

@@ -1,2 +1,2 @@
 mkdocs-material
-mkdocs-d2-plugin==1.2.3
+mkdocs-d2-plugin==1.3.0

setup.py

@@ -8,7 +8,7 @@
 
 setup(
     name="mkdocs-d2-plugin",
-    version="1.2.3",
+    version="1.3.0",
     description="MkDocs plugin for D2",
     long_description=long_description,
     long_description_content_type="text/markdown",