chore(markdown): Work on macro reference docs

markdown/dev/reference/api/macros/banner/en.md

@@ -5,22 +5,44 @@ title: banner
 The `banner` macro allows you to add repeating text along a path.
 It is provided by the [banner plugin](/reference/plugins/banner).
 
-<Example part="plugin_banner">Example of the banner macro</Example>
+## Signature
 
 ```js
-points.from = new Point(0,0)
-points.to = new Point(320,0)
-
-paths.banner = new Path()
-  .move(points.from)
-  .line(points.to)
-
 macro('banner', {
-  path: paths.banner,
+  Path path,
-  text: 'banner plugin',
+  String text,
+  Number dy=1,
+  Number spaces=12,
+  Number repeat=10,
 })
 ```
   
+## Example
+
+<Example caption="Example of the banner macro">
+```js
+({ Point, points, Path, paths, macro, part }) => {
+
+  points.from = new Point(0,0)
+  points.to = new Point(320,0)
+  
+  paths.banner = new Path()
+    .move(points.from)
+    .line(points.to)
+    .move(new Point(0,-10)) // Prevent clipping
+  
+  macro('banner', {
+    path: paths.banner,
+    text: 'banner',
+  })
+
+  return part
+}
+```
+</Example>
+
+## Configuration
+
 | Property     | Default    | Type       | Description |
 |-------------:|------------|------------|-------------|
 | `path`       |            | `Path`     | The Path to add the text on |

markdown/dev/reference/api/macros/bartack/en.md

@@ -2,30 +2,47 @@
 title: bartack
 ---
 
-The `bartack` macro allows you to add a _bartack_ marker to your sewing pattern.
+The `bartack` macro allows you to add a _bartack_ marker to your sewing
-It is provided by the [bartack plugin](/reference/plugins/bartack/).
+pattern. It is provided by the [bartack plugin](/reference/plugins/bartack/).
 
-<Example part="plugin_bartack">
+## Signature
-Example of the bartack macro
-</Example>
 
 ```js
-points.a = new Point(15, 15)
+macro('banner', {
-
+  Point anchor,
-macro('bartack', {
+  Number angle=0,
-  anchor: points.a,
+  Number density=3,
-  angle: 30,
+  Number length=15,
-  length: 15
+  String prefix='',
+  String suffix='',
+  Number width=3,
 })
 ```
 
+## Example
+
+<Example caption="Example of the bartack macro">
+```js
+({ macro, Point, part }) => {
+
+  macro('bartack', {
+    anchor: new Point(0,0),
+    length: 25
+  })
+
+  return part
+}
+```
+</Example>
+
+## Configuration
+
 | Property     | Default    | Type       | Description |
 |-------------:|------------|------------|-------------|
 | `anchor`     |            | `Point`    | The point to start the bartack from |
 | `angle`      | `0`        | `number`   | The angle under which to draw the bartack |
 | `density`    | `3`        | `number`   | Controls how close the stitches are togeter |
 | `length`     | `15`       | `number`   | Length of the bartack |
-| `nameFormat` |            | `function` | A method that receives the name of the path or point and should return the name for the cloned path and or point |
 | `prefix`     |            | `string`   | A prefix to apply to the names of the generated path and points |
 | `suffix`     |            | `string`   | A suffix to apply to the names of the generated path and points |
 | `width`      | `3`        | `number`   | Width of the bartack |

markdown/dev/reference/api/macros/bartackalong/en.md

@@ -6,39 +6,48 @@ The `bartackAlong` macro allows you to add a _bartack_ marker to your sewing pat
 More specifically, a bartack along a path.
 It is provided by the [bartack plugin](/reference/plugins/bartack/).
 
-<Example part="plugin_bartackalong">
+## Signature
-Example of the bartackAlong macro
-</Example>
 
 ```js
-points.a = new Point(15, 15)
+macro('banner', {
-points.b = new Point(20, 20)
+  Number angle=0,
-points.c = new Point(30, 20)
+  Number density=3,
-points.d = new Point(35, 15)
+  Number length=15,
-points.e = new Point(20, 10)
+  Path path,
-points.f = new Point(30, 10)
+  String prefix='',
-
+  String suffix='',
-paths.a = new Path()
+  Number width=3,
-  .move(points.a)
-  .curve(points.b, points.c, points.d)
-  .setRender(false)
-
-macro('bartackAlong', { 
-  path: paths.a 
-})
-
-macro('sprinkle', {
-  snippet: 'notch',
-  on: ['e', 'f']
 })
 ```
 
+## Example
+
+<Example caption="Example of the bartackAlong macro">
+```js
+({ Point, Path, macro, part }) => {
+
+  macro('bartackAlong', { 
+    path: new Path()
+      .move(new Point(15,15))
+      .curve(
+        new Point(20, 20),
+        new Point(30, 20),
+        new Point(35, 15),
+      )
+  })
+
+  return part
+}
+```
+</Example>
+
+## Configuration
+
 | Property     | Default    | Type       | Description |
 |-------------:|------------|------------|-------------|
 | `angle`      | `0`        | `number`   | The angle under which to draw the bartack |
 | `density`    | `3`        | `number`   | Controls how close the stitches are togeter |
 | `length`     | `15`       | `number`   | Length of the bartack |
-| `nameFormat` |            | `function` | A method that receives the name of the path or point and should return the name for the cloned path and or point |
 | `path`       |            | `Path`     | The path the bartack should follow |
 | `prefix`     |            | `string`   | A prefix to apply to the names of the generated path and points |
 | `suffix`     |            | `string`   | A suffix to apply to the names of the generated path and points |

markdown/dev/reference/api/macros/bartackfractionalong/en.md

@@ -2,46 +2,57 @@
 title: bartackFractionAlong
 ---
 
-The `bartackFractionAlong` macro allows you to add a _bartack_ marker to your sewing pattern.
+The `bartackFractionAlong` macro allows you to add a _bartack_ marker to your
-More specifically, a bartack along a fraction of a path.
+sewing pattern. More specifically, a bartack along a fraction of a path.  It
-It is provided by the [bartack plugin](/reference/plugins/bartack/).
+is provided by the [bartack plugin](/reference/plugins/bartack/).
 
-<Example part="plugin_bartackfractionalong">
+## Signature
-Example of the bartackFractionAlong macro
-</Example>
 
 ```js
-points.a = new Point(15, 15)
+macro('banner', {
-points.b = new Point(20, 20)
+  Number angle=0,
-points.c = new Point(30, 20)
+  Number density=3,
-points.d = new Point(35, 15)
+  Number end=1,
-points.e = new Point(20, 10)
+  Number length=15,
-points.f = new Point(30, 10)
+  Path path,
-
+  String prefix='',
-paths.a = new Path()
+  Number start=0,
-  .move(points.a)
+  String suffix='',
-  .curve(points.b, points.c, points.d)
+  Number width=3,
-  .setRender(false)
-
-macro('bartackFractionAlong', { 
-  path: paths.a,
-  start: 0.2,
-  end: 0.8
-})
-
-macro('sprinkle', {
-  snippet: 'notch',
-  on: ['e', 'f']
 })
 ```
 
+## Example
+
+<Example caption="Example of the bartackFractionAlong macro">
+```js
+({ Point, Path, macro, part }) => {
+
+  macro('bartackFractionAlong', { 
+    path: new Path()
+      .move(new Point(15,15))
+      .curve(
+        new Point(20, 20),
+        new Point(30, 20),
+        new Point(35, 15),
+      ),
+    start: 0.2,
+    end: 0.8,
+  })
+
+  return part
+}
+```
+</Example>
+
+## Configuration
+
 | Property     | Default    | Type       | Description |
 |-------------:|------------|------------|-------------|
 | `angle`      | `0`        | `number`   | The angle under which to draw the bartack |
 | `density`    | `3`        | `number`   | Controls how close the stitches are togeter |
 | `end`        | `1`        | `number`   | At which fraction of the path length (from `0` to `1`) should the bartack end |
 | `length`     | `15`       | `number`   | Length of the bartack |
-| `nameFormat` |            | `function` | A method that receives the name of the path or point and should return the name for the cloned path and or point |
 | `path`       |            | `Path`     | The path the bartack should follow |
 | `prefix`     |            | `string`   | A prefix to apply to the names of the generated path and points |
 | `start`      | `0`        | `number`   | At which fraction of the path length (from `0` to `1`) should the bartack start |

markdown/dev/reference/api/macros/cutonfold/en.md

@@ -5,18 +5,38 @@ title: cutonfold
 The `cutonfold` macro adds a _cut on fold_ indicator to your pattern.
 It is provided by the [cutonfold plugin](/reference/plugins/cutonfold).
 
-<Example part="plugin_cutonfold">
+## Signature
-Example of the cut on fold indicator added by this macro
-</Example>
 
 ```js
 macro('cutonfold', {
-  from: points.cofLeft,
+  Point from,
-  to: points.cofRight,
+  Boolean grainline=false,
-  grainline: true
+  Number margin=5,
+  Number offset=15,
+  String prefix='',
+  Point to,
 })
 ```
 
+## Example
+
+<Example caption="Example of the cut on fold indicator added by this macro">
+```js
+({ Point, macro, part }) => {
+
+  macro('cutonfold', {
+    from: new Point(0,0),
+    to: new Point(100,0),
+    grainline: true
+  })
+
+  return part
+}
+```
+</Example>
+
+## Configuration
+
 | Property    | Default | Type                | Description |
 |------------:|---------|---------------------|-------------|
 | `from`      |         | [Point](/reference/api/point) | The startpoint of the _cut on fold_ indicator |
@@ -25,16 +45,14 @@ macro('cutonfold', {
 | `offset`    | 15      | Number              | The distance in mm to offset from the line from start to end |
 | `grainline` | `false` | Boolean             | Whether this cutonfold indicator is also the grainline |
 
-<Note>
+## Notes
 
-###### It's safe to use a corner of your pattern part for this
+### It's safe to use a corner of your pattern part for this
 
 Since this is typically used on corners, the generated cut-on-fold indicator
 will not go all the way to the `to` and `from` points.
 
-</Note>
+### Removing the cut on fold indicator
-
-## Removing the cut on fold indicator
 
 If you inherit a part with a cut on fold indicator and you'd like to remove it,
 you can do so by passing `false` to the macro:

markdown/dev/reference/api/macros/en.md

@@ -3,17 +3,56 @@ title: Macros
 ---
 
 Macros are a way to combine different operations into a single command.
-They are provided by plugins, but can also be added without the need for
+Macros are typically provided by by plugins, but can also be added ad-hoc
-a plugin.
+without the need for a plugin.
+
+## Signature
+
+```js
+null macro(object config, object props)
+```
+
+A macro receives a single configuration object as its first parameter.
+The second parameter is the same object received by [the draft method in a
+part](/reference/api/part/draft)
+
+## Example
+
+```js
+pattern.use({
+  name: 'My adhoc plugin',
+  macros: {
+    myMacro: function (so, props) {
+      // Do something wonderful here
+    },
+    myOtherMacro: function (so, props) {
+      // Do something wonderful here
+    },
+  }
+}
+```
+
+Now you can use these macros in your part:
+
+```js
+({ macro, part }) => {
+
+  macro('myMacro', {
+    some: [ 'config', 'here' ],
+    more: 'config'
+  })
+  macro('myOtherMacro', 'Just a string')
+
+  return part
+}
+```
+
+## Macros we maintain
 
 Below is a list of macros from [the plugins we maintain](/reference/plugins):
 
 <ReadMore list />
 
-<Note>All macros take a single object as their configuration. </Note>
+## Notes
 
-<Tip>
+We recommend allowing to *undo* a macro by passing `false` as its parameter.
-
-For more info on a specific macro and examples, follow the link to the plugin that provides the macro.
-
-</Tip>

markdown/dev/reference/api/macros/flip/en.md

@@ -2,20 +2,44 @@
 title: flip
 ---
 
-The `flip` macro flips (mirrors) an entire part vertically around either the X-axis or the Y-axis.  
+The `flip` macro flips (mirrors) an entire part vertically around either the
-It is provided by the [flip plugin](/reference/plugins/flip).
+X-axis or the Y-axis.  It is provided by the [flip
+plugin](/reference/plugins/flip).
+
+## Signature
 
 ```js
-macro("flip", { 
+macro('flip', { String axis=x })
-  axis: 'x' 
-})
 ```
 
+## Example
+
+<Example caption="Example of the flip macro">
+```js
+({ Point, points, Path, paths, Snippet, snippets, macro, part }) => {
+
+  points.a = new Point(0,0)
+  points.b = new Point(90,20)
+  paths.a = new Path().move(points.a).line(points.b).setClass('dotted note')
+  snippets.a = new Snippet(
+    'logo', 
+    paths.a.shiftFractionAlong(0.5)
+  ).attr('data-scale', 0.2)
+
+  macro('flip')
+  
+  return part
+}
+```
+</Example>
+
+## Configuration
+
 | Property        | Default | Type                | Description |
 |----------------:|---------|---------------------|-------------|
 | `axis`          | 'x'     | The axis to flip around. Either `x` or `y` |
 
-<Note>
+## Notes
 
 Under the hood, this macro will:
 
@@ -23,4 +47,3 @@ Under the hood, this macro will:
 - Go through all the Paths in your Part, and for each drawing operation will multiply the (X or Y)-coordinare by -1
 - Go through all the Snippets in your Part and multiply the (X or Y)-coordinate of the anchor point by -1
 
-</Note>

markdown/dev/reference/api/macros/gore/en.md

@@ -2,29 +2,52 @@
 title: gore
 ---
 
-The `gore` macro facilitates the drafting of [gores][1] which are typically used in hats.
+The `gore` macro facilitates the drafting of [gores][1] which are typically
+used in hats.
 It is provided by the [gore plugin](/reference/plugins/grainline/).
 
-<Example part="plugin_gore">Example of a gore as drafted by this macro</Example>
+## Signature
 
 ```js
-macro("gore", {
+macro('gore', { 
-  from: points.anchor,
+  Point from,
-  radius: measurements.head,
+  Number radius,
-  gores: 6,
+  Number gores,
-  extraLength: 20,
+  Number extraLength,
-  render: true,
+  Boolean hidden=true,
-  class: 'fabric',
+  String class='',
-})
+)
 ```
 
+## Example
+
+<Example caption="Example of the gore macro">
+```js
+({ Point, macro, part }) => {
+
+  macro('gore', { 
+    from: new Point(0,0),
+    radius: 100,
+    gores: 6,
+    extraLength: 20,
+    hidden: false,
+    class: 'fabric',
+  })
+  
+  return part
+}
+```
+</Example>
+
+## Configuration
+
 | Property      | Default | Type       | Description                                  |
 |--------------:|---------|------------|----------------------------------------------|
 | `from`        |         | [Point][2] | The point to start drafting the gore from |
 | `radius`      |         | number     | The radius of the sphere the gores should cover |
 | `gores`       |         | number     | The text to put on the _grainline_ indicator |
 | `extraLength` |         | number     | The length of the straight section after a complete semisphere |
-| `render`      | `false` | boolean    | Whether or not to render the generated path |
+| `hidden`      | `true`  | boolean    | Whether or not to hide the generated path |
 | `class`       |         | boolean    | Any classes to add to the generated path |
 
 [1]: https://en.wikipedia.org/wiki/Gore_\(segment\)

sites/shared/components/mdx/example/index.js

@@ -1,6 +1,8 @@
 import { Tab, Tabs } from '../tabs.js'
 import Md from 'react-markdown'
-import { plugin } from '@freesewing/plugin-bundle'
+import { pluginBundle } from '@freesewing/plugin-bundle'
+import { pluginFlip } from '@freesewing/plugin-flip'
+import { pluginGore } from '@freesewing/plugin-gore'
 import { Design } from '@freesewing/core'
 import Svg from '../../workbench/draft/svg'
 import Defs from '../../workbench/draft/defs'
@@ -63,7 +65,7 @@ const buildExample = (children, settings = { margin: 10 }) => {
   const part = {
     draft,
     measurements: [],
-    plugins: [plugin],
+    plugins: [pluginBundle, pluginFlip, pluginGore],
   }
   const design = new Design({ parts: [part] })
   return new design(settings)