From c5f0b7955491072ff67921527ebd3a01a2dc0c93 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:10:49 +0200
Subject: [PATCH 01/10] [DATALAD RUNCMD] add filetree macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_filetree_example/i \\<!-- This block generates a file tree.\\nA guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 .../01-magnetic-resonance-imaging-data.md     | 32 +++++++++++++
 .../02-magnetoencephalography.md              |  8 ++++
 .../04-intracranial-electroencephalography.md |  8 ++++
 .../05-task-events.md                         | 12 +++++
 ...logical-and-other-continuous-recordings.md | 12 +++++
 .../10-microscopy.md                          | 20 ++++++++
 src/05-derivatives/02-common-data-types.md    | 20 ++++++++
 src/05-derivatives/03-imaging.md              | 48 +++++++++++++++++++
 src/99-appendices/06-meg-file-formats.md      | 40 ++++++++++++++++
 src/99-appendices/11-qmri.md                  | 36 ++++++++++++++
 10 files changed, 236 insertions(+)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 41969de679..bfb492d7d3 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -273,6 +273,10 @@ which are typically used in `part-mag`/`part-phase` or `part-real`/`part-imag`
 pairs of files.
 For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -426,6 +430,10 @@ for more information on `dir` field specification.
 Multi-echo data MUST be split into one file per echo using the
 [`echo-<index>`](../99-appendices/09-entities.md#echo) key-value pair. For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -456,6 +464,10 @@ name with the exception of the `part-<mag|phase>` or `part-<real|imag>` key/valu
 
 For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -540,6 +552,10 @@ additional terms and their definitions.
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -707,6 +723,10 @@ two runs each, and the intent of the researcher is that all of them are
 part of a unique multipart scan, then they will tag all four runs with the
 same `MultipartID` (shown at the right-hand side of the file listing):
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-1": {
@@ -723,6 +743,10 @@ same `MultipartID` (shown at the right-hand side of the file listing):
 If, conversely, the researcher wanted to store two multipart scans, one possibility
 is to combine matching phase-encoding directions:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-1": {
@@ -739,6 +763,10 @@ is to combine matching phase-encoding directions:
 Alternatively, the researcher's intent could be combining opposed phase-encoding
 runs instead:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-1": {
@@ -755,6 +783,10 @@ runs instead:
 The `MultipartID` metadata MAY be used with the
 [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair, for example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-1": {
diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md
index 7ba79f7c45..c5167a3d9c 100644
--- a/src/04-modality-specific-files/02-magnetoencephalography.md
+++ b/src/04-modality-specific-files/02-magnetoencephalography.md
@@ -454,6 +454,10 @@ manufacturer (see [Appendix VI](../99-appendices/06-meg-file-formats.md)).
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-control01": {
@@ -492,6 +496,10 @@ SHOULD be present as well.
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-control01": {},
diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
index e4d1b0cbf8..e9ac6b4692 100644
--- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md
+++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
@@ -321,6 +321,10 @@ correspond.
 
 For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -489,6 +493,10 @@ Example of the operative photo of ECoG electrodes (here is an annotated example
 which electrodes and vasculature are marked, taken from Hermes et al.,
 JNeuroMeth 2010).
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md
index 5188a8c1ae..6426d719f2 100644
--- a/src/04-modality-specific-files/05-task-events.md
+++ b/src/04-modality-specific-files/05-task-events.md
@@ -62,6 +62,10 @@ SHOULD be documented in an accompanying JSON sidecar file.
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-control01": {
@@ -102,6 +106,10 @@ sake of brevity.
 For multi-echo files, the `events.tsv` file is applicable to all echos of
 a particular run:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -153,6 +161,10 @@ The following example includes references to the
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-control01": {
diff --git a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
index 3bf43c7532..1317b7f645 100644
--- a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
+++ b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
@@ -68,6 +68,10 @@ as well as to make support for other file formats possible in the future.
 
 Example `*_physio.tsv.gz`:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-control01": {
@@ -88,6 +92,10 @@ Example `*_physio.tsv.gz`:
 
 Example `*_physio.json`:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-control01": {
@@ -140,6 +148,10 @@ For multi-echo data, a given `physio.tsv` file is applicable to all echos of
 a particular run.
 For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
diff --git a/src/04-modality-specific-files/10-microscopy.md b/src/04-modality-specific-files/10-microscopy.md
index 4c03988744..463067224f 100644
--- a/src/04-modality-specific-files/10-microscopy.md
+++ b/src/04-modality-specific-files/10-microscopy.md
@@ -94,6 +94,10 @@ The label MUST be unique per subject and is RECOMMENDED to be unique throughout
 For example: Three brain slices (`sample-01` to `sample-03`) extracted from subject `sub-01`,
 imaged by scanning electron microscopy (SEM) in PNG format
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -126,6 +130,10 @@ For example: One brain slice (`sample-01`) extracted from subject `sub-01` with
 stains (`stain-01`, `stain-02` and `stain-03`) in three separate files, imaged by selective plane
 illumination microscopy (SPIM) in OME-TIFF format
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -179,6 +187,10 @@ Figure 1: Examples of chunks configurations.
 For example: Four chunks (`chunk-01` to `chunk-04`) from the same brain sample (`sample-01`)
 of subject `sub-01`, imaged by confocal microscopy (CONF) in OME-TIFF format
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -213,6 +225,10 @@ Lower resolutions files MUST be placed under the `derivatives` folder and use th
 
 For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "my_dataset": {
@@ -418,6 +434,10 @@ acquisition of different photos of the same sample.
 
 For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 9dbe604706..3ce1dbe347 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -28,6 +28,10 @@ The location of the file in the original datasets is encoded in the `RawSources`
 and [`_desc-<label>`](../99-appendices/09-entities.md#desc)
 is used to prevent clashing with the original filename.
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -107,6 +111,10 @@ For CIFTI-2 images, the relevant structures are BrainStructure values defined in
 Preprocessed `bold` NIfTI file in `individual` coordinate space. Please mind
 that in this case `SpatialReference` key is REQUIRED.
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -130,6 +138,10 @@ In this example, because all volumetric structures are sampled to the same
 reference, the `VolumeReference` key is used as a default, and only the
 surface references need to be specified by BrainStructure names.
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
    "sub-01": {
@@ -187,6 +199,10 @@ processing for the same input data.
 
 Examples of preprocessed data:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline1": {
@@ -204,6 +220,10 @@ Examples of preprocessed data:
    }
 ) }}
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline2": {
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 6814889c6c..cf394fa5a2 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -32,6 +32,10 @@ to present both [`res`](../99-appendices/09-entities.md#res) and
 
 Examples:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline1": {
@@ -94,6 +98,10 @@ Example of CIFTI-2 files (a format that combines regularly sampled data
 and non-parametric surfaces) having both [`res`](../99-appendices/09-entities.md#res)
 and [`den`](../99-appendices/09-entities.md#den) entities:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline1": {
@@ -158,6 +166,10 @@ JSON metadata fields:
 
 Examples:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "func_loc": {
@@ -171,6 +183,10 @@ Examples:
    }
 ) }}
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "manual_masks": {
@@ -240,6 +256,10 @@ Template:
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline": {
@@ -264,6 +284,10 @@ the [`atlas` entity](../99-appendices/09-entities.md#atlas) and the
 
 For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline": {
@@ -297,6 +321,10 @@ Template:
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline": {
@@ -316,6 +344,10 @@ for reserved key values for [`label`](../99-appendices/09-entities.md#label).
 A 4D probabilistic segmentation, in which each frame corresponds to a different
 tissue class, must provide a label mapping in its JSON sidecar. For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline": {
@@ -365,6 +397,10 @@ The [`hemi-<label>`](../99-appendices/09-entities.md#hemi) entity is REQUIRED fo
 a structure that is restricted to a hemibrain.
 For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline": {
@@ -380,6 +416,10 @@ For example:
 
 The REQUIRED extension for CIFTI parcellations is `.dlabel.nii`. For example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline": {
@@ -420,6 +460,10 @@ filename.
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline": {
@@ -438,6 +482,10 @@ segmentations in relative subdirectories.
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "pipeline": {
diff --git a/src/99-appendices/06-meg-file-formats.md b/src/99-appendices/06-meg-file-formats.md
index 7036eb32a0..94060f5633 100644
--- a/src/99-appendices/06-meg-file-formats.md
+++ b/src/99-appendices/06-meg-file-formats.md
@@ -36,6 +36,10 @@ such as the CTF newDs command-line application or
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-control01": {
@@ -95,6 +99,10 @@ which may be nested inside a `ses-<label>` folder, as shown in the following exa
 
 #### Example with single session (omitted session folder)
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-01": {
@@ -122,6 +130,10 @@ which may be nested inside a `ses-<label>` folder, as shown in the following exa
 
 #### Example with multiple sessions
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-01": {
@@ -159,6 +171,10 @@ and placed in a `derivatives` subfolder.
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-control01": {
@@ -200,6 +216,10 @@ for the `acq_time` column in `scans.tsv` MUST all be identical, as described in
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-control01": {
@@ -243,6 +263,10 @@ files for each run inside (for example, `c,rfhp0.1Hz`, `config` and `hs_file`).
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-control01": {
@@ -262,6 +286,10 @@ Example:
 
 Where:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-control01_ses-001_task-rest_run-01_meg": {
@@ -286,6 +314,10 @@ Head points and marker points in *head space* are acquired using third-party har
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-control01": {
@@ -343,6 +375,10 @@ sub-<label>[_ses-<label>]_task-<label>[_acq-<label>]_digitizer.txt
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-control01": {
@@ -377,6 +413,10 @@ information).
 
 Example:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-control01": {
diff --git a/src/99-appendices/11-qmri.md b/src/99-appendices/11-qmri.md
index 6c4a349907..a201904a14 100644
--- a/src/99-appendices/11-qmri.md
+++ b/src/99-appendices/11-qmri.md
@@ -43,6 +43,10 @@ If a qMRI file collection is intended for creating structural quantitative maps
 files belonging to that collection are stored in the `anat` subfolder.
 Below is an example file collection for `MP2RAGE`:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-01": {
@@ -63,6 +67,10 @@ As these images do not convey substantial structural information,
 respective file collections of RF fieldmaps are stored in the `fmap` subfolder.
 Below is an example file collection for RF transmit field map `TB1EPI`:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-01": {
@@ -89,6 +97,10 @@ For example a `T1map` can be generated from an `MP2RAGE` file collection using e
 
 If the map is post-generated:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "ds-example": {
@@ -110,6 +122,10 @@ If the map is post-generated:
 
 If the map is pre-generated, for example, by a Siemens scanner:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "ds-example": {
@@ -196,6 +212,10 @@ As qMRI maps are stored as derivatives, they are subjected to the metadata requi
 
 An example `dataset_description.json` for a qMRI map derivatives folder:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "ds-example": {
@@ -500,6 +520,10 @@ files:
 To properly identify constituents of this particular method, values of the `echo`
 entity MUST index the images as follows:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-01": {
@@ -534,6 +558,10 @@ and MAY be followed by freeform entries:
 | `_acq-tr1Test`   | `_acq-tr2Test`   | Acquisition `Test`   |
 | `_acq-tr1Retest` | `_acq-tr2Retest` | Acquisition `Retest` |
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-01": {
@@ -562,6 +590,10 @@ values of the `acq` entity SHOULD begin with either `anat` or `famp` and MAY be
 | `_acq-anatTest`             | `_acq-fampTest`           | Acquisition `Test`   |
 | `_acq-anatRetest`           | `_acq-fampRetest`         | Acquisition `Retest` |
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-01": {
@@ -594,6 +626,10 @@ entries:
 | `_acq-bodyPDw` | `_acq-headPDw` | `PDw` for `MPM`    |
 | `_acq-bodyT1w` | `_acq-headT1w` | `T1w` for `MPM`    |
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
    {
     "sub-01": {

From 42632b84997fd21463ff34c0288426eef2c5df8e Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:10:56 +0200
Subject: [PATCH 02/10] [DATALAD RUNCMD] add filetree macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_filetree_example/i \\<!-- This block generates a file tree.\\nA guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 src/02-common-principles.md                   | 28 +++++++++++++++++++
 src/06-longitudinal-and-multi-site-studies.md |  4 +++
 2 files changed, 32 insertions(+)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index d993224cd5..5920c2cac1 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -265,6 +265,10 @@ However, in the case that these data are to be included:
 
 Alternatively one can organize their data in the following way
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "my_dataset-1": {
@@ -358,6 +362,10 @@ Derivatives can be stored/distributed in two ways:
 
     Example of a derivative dataset including the raw dataset as source:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
     {{ MACROS___make_filetree_example(
         {
         "my_processed_data": {
@@ -590,6 +598,10 @@ Corollaries:
 
 Example 1: Demonstration of inheritance principle
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "sub-01": {
@@ -633,6 +645,10 @@ absence in the metadata file at the lower level (rule 5.b; corollary 3).
 
 Example 2: Impermissible use of multiple metadata files at one directory level (rule 4)
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "sub-01": {
@@ -654,6 +670,10 @@ Example 2: Impermissible use of multiple metadata files at one directory level (
 Example 3: Modification of filesystem structure from Example 2 to satisfy inheritance
 principle requirements
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "sub-01": {
@@ -674,6 +694,10 @@ principle requirements
 
 Example 4: Single metadata file applying to multiple data files (corollary 2)
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "sub-01": {
@@ -821,6 +845,10 @@ This is an example of the folder and file structure. Because there is only one
 session, the session level is not required by the format. For details on
 individual files see descriptions in the next section:
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "sub-control01": {
diff --git a/src/06-longitudinal-and-multi-site-studies.md b/src/06-longitudinal-and-multi-site-studies.md
index 568c80c9c7..e7abffbe40 100644
--- a/src/06-longitudinal-and-multi-site-studies.md
+++ b/src/06-longitudinal-and-multi-site-studies.md
@@ -5,6 +5,10 @@ and [filenames](02-common-principles.md#file-name-structure)
 in the form of a session (for example `ses-<label>`) and
 with a [`*_sessions.tsv` file](03-modality-agnostic-files.md#sessions-file).
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "sub-control01": {

From 84a7ee026c2cf0b2f1c950fdb51afa22b5f659d4 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:13:42 +0200
Subject: [PATCH 03/10] [DATALAD RUNCMD] add metadata table macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_metadata_table/i \\<!-- This block generates a metadata table.\\nThe definitions of these fields can be found in\\n  src/schema/objects/metadata.yaml\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 src/02-common-principles.md       |  6 ++++++
 src/03-modality-agnostic-files.md | 18 ++++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 5920c2cac1..fd54ad1a20 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -467,6 +467,12 @@ Note that if a field name included in the data dictionary matches a column name
 then that field MUST contain a description of the corresponding column,
 using an object containing the following fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
         "LongName": "OPTIONAL",
diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 822bb197c7..a8ae9db9b4 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -14,6 +14,12 @@ Templates:
 The file `dataset_description.json` is a JSON file describing the dataset.
 Every dataset MUST include this file with the following fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Name": "REQUIRED",
@@ -99,6 +105,12 @@ top level of every derived dataset:
 In contrast to raw BIDS datasets, derived BIDS datasets MUST include a
 `GeneratedBy` key:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "GeneratedBy": "REQUIRED"
@@ -348,6 +360,12 @@ MAY be accompanied by a JSON file describing the columns in detail
 
 In addition to the column descriptions, the JSON file MAY contain the following fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "MeasurementToolMetadata": "OPTIONAL",

From 01d6531ee26f1a6d7f80d70be8e05514a44242a6 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:13:49 +0200
Subject: [PATCH 04/10] [DATALAD RUNCMD] add metadata table macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_metadata_table/i \\<!-- This block generates a metadata table.\\nThe definitions of these fields can be found in\\n  src/schema/objects/metadata.yaml\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 .../01-magnetic-resonance-imaging-data.md     | 138 ++++++++++++++++++
 .../02-magnetoencephalography.md              |  66 +++++++++
 .../03-electroencephalography.md              |  48 ++++++
 .../04-intracranial-electroencephalography.md |  42 ++++++
 .../05-task-events.md                         |  12 ++
 ...logical-and-other-continuous-recordings.md |  12 ++
 .../07-behavioral-experiments.md              |   6 +
 .../08-genetic-descriptor.md                  |  12 ++
 .../09-positron-emission-tomography.md        |  42 ++++++
 .../10-microscopy.md                          |  24 +++
 src/05-derivatives/02-common-data-types.md    |  12 ++
 src/05-derivatives/03-imaging.md              |  18 +++
 src/99-appendices/11-qmri.md                  |   6 +
 13 files changed, 438 insertions(+)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index bfb492d7d3..4914e80ef4 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -12,6 +12,12 @@ by Ben Inglis.
 
 ### Scanner Hardware
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Manufacturer": ("RECOMMENDED", "Corresponds to DICOM Tag 0008, 0070 `Manufacturer`."),
@@ -50,6 +56,12 @@ that a given scan was collected with the intended coil elements selected
 
 ### Sequence Specifics
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "PulseSequenceType": "RECOMMENDED",
@@ -76,6 +88,12 @@ that a given scan was collected with the intended coil elements selected
 
 ### In-Plane Spatial Encoding
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "NumberShots": "RECOMMENDED",
@@ -117,6 +135,12 @@ and the center of the last "effective" echo, sometimes called the "FSL definitio
 
 ### Timing Parameters
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "EchoTime": "RECOMMENDED, but REQUIRED if corresponding fieldmap data is present, or the data comes from a multi echo sequence or Arterial Spin Labeling",
@@ -129,6 +153,12 @@ and the center of the last "effective" echo, sometimes called the "FSL definitio
 
 ### RF & Contrast
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "FlipAngle": "RECOMMENDED, but REQUIRED if `LookLocker` is set `true`",
@@ -138,6 +168,12 @@ and the center of the last "effective" echo, sometimes called the "FSL definitio
 
 ### Slice Acceleration
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "MultibandAccelerationFactor": "RECOMMENDED",
@@ -148,6 +184,12 @@ and the center of the last "effective" echo, sometimes called the "FSL definitio
 
 Useful for multimodal co-registration with MEG, (S)EEG, TMS, and so on.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "AnatomicalLandmarkCoordinates__mri": "RECOMMENDED",
@@ -168,6 +210,12 @@ The modality labels `dwi` (under `dwi/`), `bold` (under `func/`),
 any modality under `fmap/` are allowed to encode the MR protocol intent for
 fieldmap estimation using the following metadata:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "B0FieldIdentifier": "RECOMMENDED",
@@ -177,6 +225,12 @@ fieldmap estimation using the following metadata:
 
 ### Institution information
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "InstitutionName": ("RECOMMENDED", "Corresponds to DICOM Tag 0008, 0080 `InstitutionName`."),
@@ -256,6 +310,12 @@ JSON file. See [Common metadata fields](#common-metadata-fields) for a
 list of terms and their definitions. There are also some OPTIONAL JSON
 fields specific to anatomical scans:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "ContrastBolusIngredient": "OPTIONAL",
@@ -490,6 +550,12 @@ JSON file.
 
 ### Required fields
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "RepetitionTime": "REQUIRED",
@@ -507,6 +573,12 @@ combined image rather than an image from each coil.
 
 #### Timing Parameters
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "NumberOfVolumesDiscardedByScanner": "RECOMMENDED",
@@ -538,6 +610,12 @@ sparse sequences.
 
 #### fMRI task information
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Instructions": ("RECOMMENDED", "This is especially important in context of resting state recordings and distinguishing between eyes open and eyes closed paradigms."),
@@ -704,6 +782,12 @@ not be able to be directly concatenated.
 BIDS permits defining arbitrary groupings of these multipart scans with the
 following metadata:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "MultipartID": "REQUIRED",
@@ -882,6 +966,12 @@ See [Appendix XII - ASL](../99-appendices/12-arterial-spin-labeling.md#summary-i
 
 #### Common metadata fields applicable to both (P)CASL and PASL
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "ArterialSpinLabelingType": "REQUIRED",
@@ -907,6 +997,12 @@ See [Appendix XII - ASL](../99-appendices/12-arterial-spin-labeling.md#summary-i
 
 These fields can only be used when `ArterialSpinLabelingType` is `"CASL"` or `"PCASL"`. See [Appendix XII - ASL](../99-appendices/12-arterial-spin-labeling.md#pcasl-sequence) for more information on the (P)CASL sequence and the Labeling Pulse fields.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "LabelingDuration": "REQUIRED",
@@ -925,6 +1021,12 @@ These fields can only be used when `ArterialSpinLabelingType` is `"CASL"` or `"P
 
 These fields can only be used when `ArterialSpinLabelingType` is `PASL`. See [Appendix XII - ASL](../99-appendices/12-arterial-spin-labeling.md#pasl-sequence) for more information on the PASL sequence and the BolusCutOff fields.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "BolusCutOffFlag": "REQUIRED",
@@ -939,6 +1041,12 @@ These fields can only be used when `ArterialSpinLabelingType` is `PASL`. See [Ap
 
 Some common metadata fields are REQUIRED for the `*_m0scan.json`: `EchoTime`, `RepetitionTimePreparation`, and `FlipAngle` in case `LookLocker` is `true`.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "IntendedFor": (
@@ -1029,6 +1137,12 @@ tools that support older datasets.
 Fieldmap data MAY be linked to the specific scan(s) it was acquired for by
 filling the `IntendedFor` field in the corresponding JSON file.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "IntendedFor": (
@@ -1070,6 +1184,12 @@ the OPTIONAL `_magnitude2` image to the longer echo time.
 
 Required fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "EchoTime1": "REQUIRED",
@@ -1101,6 +1221,12 @@ second echos are available.
 
 Required fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "EchoTime__fmap": "REQUIRED",
@@ -1125,6 +1251,12 @@ In some cases (for example GE), the scanner software will directly reconstruct a
 
 Required fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Units": (
@@ -1173,6 +1305,12 @@ the REQUIRED `PhaseEncodingDirection` metadata field
 
 Required fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "PhaseEncodingDirection": "REQUIRED",
diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md
index c5167a3d9c..7ff5711635 100644
--- a/src/04-modality-specific-files/02-magnetoencephalography.md
+++ b/src/04-modality-specific-files/02-magnetoencephalography.md
@@ -91,6 +91,12 @@ systems (see [coordinates section](#coordinate-system-json-_coordsystemjson) bel
 
 Generic fields MUST be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "TaskName": ("REQUIRED", "A RECOMMENDED convention is to name resting state task using labels beginning with `rest`."),
@@ -101,6 +107,12 @@ SHOULD be present: For consistency between studies and institutions, we
 encourage users to extract the values of these fields from the actual raw data.
 Whenever possible, please avoid using ad-hoc wording.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "InstitutionName": "RECOMMENDED",
@@ -130,6 +142,12 @@ Whenever possible, please avoid using ad-hoc wording.
 
 Specific MEG fields MUST be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "SamplingFrequency": ("REQUIRED", "The sampling frequency of data channels that deviate from the main sampling frequency SHOULD be specified in the `channels.tsv` file."),
@@ -143,6 +161,12 @@ Specific MEG fields MUST be present:
 
 SHOULD be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "MEGChannelCount": "RECOMMENDED",
@@ -171,6 +195,12 @@ Specific EEG fields
 (if recorded with MEG, see [Recording EEG simultaneously with MEG](#recording-eeg-simultaneously-with-meg)
 SHOULD be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "EEGPlacementScheme": "OPTIONAL",
@@ -320,6 +350,12 @@ EEG, head localization coils, and anatomical landmarks.
 
 MEG and EEG sensors:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "MEGCoordinateSystem": "REQUIRED",
@@ -340,6 +376,12 @@ MEG and EEG sensors:
 
 Head localization coils:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "HeadCoilCoordinates": "OPTIONAL",
@@ -351,6 +393,12 @@ Head localization coils:
 
 Digitized head points:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "DigitizedHeadPoints": "OPTIONAL",
@@ -362,6 +410,12 @@ Digitized head points:
 
 Anatomical MRI:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "IntendedFor": (
@@ -375,6 +429,12 @@ Anatomical MRI:
 
 Anatomical landmarks:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "AnatomicalLandmarkCoordinates": "OPTIONAL",
@@ -402,6 +462,12 @@ session-specific labels for example, "NAS-session1": `[127,213,139]`,"NAS-sessio
 
 Fiducials information:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "FiducialsDescription": "OPTIONAL",
diff --git a/src/04-modality-specific-files/03-electroencephalography.md b/src/04-modality-specific-files/03-electroencephalography.md
index 2df55c6a54..6567481ab4 100644
--- a/src/04-modality-specific-files/03-electroencephalography.md
+++ b/src/04-modality-specific-files/03-electroencephalography.md
@@ -79,6 +79,12 @@ be specified.
 
 Generic fields MUST be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "TaskName": ("REQUIRED", "A RECOMMENDED convention is to name resting state task using labels beginning with `rest`."),
@@ -89,6 +95,12 @@ SHOULD be present: For consistency between studies and institutions, we
 encourage users to extract the values of these fields from the actual raw data.
 Whenever possible, please avoid using ad hoc wording.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "InstitutionName": "RECOMMENDED",
@@ -107,6 +119,12 @@ Whenever possible, please avoid using ad hoc wording.
 
 Specific EEG fields MUST be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "EEGReference": "REQUIRED",
@@ -118,6 +136,12 @@ Specific EEG fields MUST be present:
 
 SHOULD be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "CapManufacturer": "RECOMMENDED",
@@ -360,6 +384,12 @@ head.
 
 General fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "IntendedFor": (
@@ -372,6 +402,12 @@ General fields:
 
 Fields relating to the EEG electrode positions:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "EEGCoordinateSystem": "REQUIRED",
@@ -382,6 +418,12 @@ Fields relating to the EEG electrode positions:
 
 Fields relating to the position of fiducials measured during an EEG session/run:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "FiducialsDescription": "OPTIONAL",
@@ -394,6 +436,12 @@ Fields relating to the position of fiducials measured during an EEG session/run:
 
 Fields relating to the position of anatomical landmark measured during an EEG session/run:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "AnatomicalLandmarkCoordinates": "RECOMMENDED",
diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
index e9ac6b4692..a3f3a9f0a9 100644
--- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md
+++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
@@ -92,6 +92,12 @@ please avoid using ad hoc wording.
 
 Generic fields MUST be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "TaskName": ("REQUIRED", "A RECOMMENDED convention is to name resting state task using labels beginning with `rest`."),
@@ -104,6 +110,12 @@ SHOULD be present: For consistency between studies and institutions, we
 encourage users to extract the values of these fields from the actual raw data.
 Whenever possible, please avoid using ad hoc wording.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "InstitutionName": "RECOMMENDED",
@@ -122,6 +134,12 @@ Whenever possible, please avoid using ad hoc wording.
 
 Specific iEEG fields MUST be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "iEEGReference": "REQUIRED",
@@ -133,6 +151,12 @@ Specific iEEG fields MUST be present:
 
 Specific iEEG fields SHOULD be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "DCOffsetCorrection": "DEPRECATED",
@@ -159,6 +183,12 @@ Specific iEEG fields SHOULD be present:
 
 Specific iEEG fields MAY be present:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "ElectricalStimulation": "OPTIONAL",
@@ -391,6 +421,12 @@ also be specified.
 
 General fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "IntendedFor": (
@@ -413,6 +449,12 @@ General fields:
 
 Fields relating to the iEEG electrode positions:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "iEEGCoordinateSystem": "REQUIRED",
diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md
index 6426d719f2..fe192cbe81 100644
--- a/src/04-modality-specific-files/05-task-events.md
+++ b/src/04-modality-specific-files/05-task-events.md
@@ -214,6 +214,12 @@ sake of brevity.
 It is RECOMMENDED to include details of the stimulus presentation software,
 when applicable:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "StimulusPresentation": "RECOMMENDED",
@@ -222,6 +228,12 @@ when applicable:
 
 The object supplied for `StimulusPresentation` SHOULD include the following key-value pairs:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "OperatingSystem": "RECOMMENDED",
diff --git a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
index 1317b7f645..be739d38d7 100644
--- a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
+++ b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
@@ -48,6 +48,12 @@ and a JSON file for storing the following metadata fields.
 Note that when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying
 `*_<physio|stim>.json` MUST be supplied as well.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "SamplingFrequency": "REQUIRED",
@@ -170,6 +176,12 @@ A guide for using macros can be found at
 The following RECOMMENDED metadata can also be added in the side-car JSON files
 of any `*_<physio>.tsv.gz` file.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Manufacturer": "RECOMMENDED",
diff --git a/src/04-modality-specific-files/07-behavioral-experiments.md b/src/04-modality-specific-files/07-behavioral-experiments.md
index 0406871b15..e0a1ec2946 100644
--- a/src/04-modality-specific-files/07-behavioral-experiments.md
+++ b/src/04-modality-specific-files/07-behavioral-experiments.md
@@ -36,6 +36,12 @@ In addition to the metadata that is either:
 
 it is RECOMMENDED to add the following metadata to the JSON files of this folder:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "TaskName": "RECOMMENDED",
diff --git a/src/04-modality-specific-files/08-genetic-descriptor.md b/src/04-modality-specific-files/08-genetic-descriptor.md
index bdd7d3fa08..08986ef578 100644
--- a/src/04-modality-specific-files/08-genetic-descriptor.md
+++ b/src/04-modality-specific-files/08-genetic-descriptor.md
@@ -27,6 +27,12 @@ Datasets linked to a genetic database entry include the following REQUIRED or OP
 `dataset_description.json` keys (a dot in the key name denotes a key in a sub-[object][],
 see the example further below):
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Genetics.Dataset": "REQUIRED",
@@ -90,6 +96,12 @@ Datasets containing the `Genetics` field in `dataset_description.json` or the
 `genetic_id` column in `participants.tsv` MUST include this file with the following
 fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "GeneticLevel": "REQUIRED",
diff --git a/src/04-modality-specific-files/09-positron-emission-tomography.md b/src/04-modality-specific-files/09-positron-emission-tomography.md
index 04c6524c98..c924fdd1a6 100644
--- a/src/04-modality-specific-files/09-positron-emission-tomography.md
+++ b/src/04-modality-specific-files/09-positron-emission-tomography.md
@@ -133,6 +133,12 @@ which we divide into several categories:
 
 #### Scanner Hardware
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Manufacturer": ("REQUIRED", "Corresponds to DICOM Tag 0008, 0070 `Manufacturer`."),
@@ -152,6 +158,12 @@ which we divide into several categories:
 
 #### Radiochemistry
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "TracerName": ("REQUIRED", "Corresponds to DICOM Tags (0008,0105) `Mapping Resource` and (0008,0122) `Mapping Resource Name`."),
@@ -184,6 +196,12 @@ which we divide into several categories:
 
 #### Pharmaceuticals
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "PharmaceuticalName": ("RECOMMENDED", "Corresponds to DICOM Tag (0008,0034) `Intervention Drug Name`."),
@@ -197,6 +215,12 @@ which we divide into several categories:
 
 #### Time
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "TimeZero": "REQUIRED",
@@ -213,6 +237,12 @@ We refer to the common principles for the standards for describing dates and tim
 
 #### Reconstruction
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "AcquisitionMode": "REQUIRED",
@@ -330,6 +360,12 @@ Innis et al. 2007 ([doi:10.1038/sj.jcbfm.9600493](https://doi.org/10.1038/sj.jcb
 Some metadata about the recording MUST be provided in an additional JSON
 file.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "PlasmaAvail": "REQUIRED",
@@ -347,6 +383,12 @@ file.
 
 The following metadata SHOULD or MUST be provided if corresponding flags are `true`.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "PlasmaFreeFraction": "RECOMMENDED if `PlasmaAvail` is `true`",
diff --git a/src/04-modality-specific-files/10-microscopy.md b/src/04-modality-specific-files/10-microscopy.md
index 463067224f..103dbc9092 100644
--- a/src/04-modality-specific-files/10-microscopy.md
+++ b/src/04-modality-specific-files/10-microscopy.md
@@ -261,6 +261,12 @@ Microscopy data MUST be described by metadata fields, stored in sidecar JSON fil
 
 #### Device Hardware
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Manufacturer": "RECOMMENDED",
@@ -276,6 +282,12 @@ Microscopy data MUST be described by metadata fields, stored in sidecar JSON fil
 
 #### Image Acquisition
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "PixelSize": "REQUIRED",
@@ -290,6 +302,12 @@ Microscopy data MUST be described by metadata fields, stored in sidecar JSON fil
 
 #### Sample
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "BodyPart": ("RECOMMENDED", "From [DICOM Body Part Examined](http://dicom.nema.org/medical/dicom/current/output/chtml/part16/chapter_L.html#chapter_L) (for example `\"BRAIN\"`)."),
@@ -324,6 +342,12 @@ of the same sample in an implicit coordinate system.
 
 -   Other transformations should be described in derivatives.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "ChunkTransformationMatrix": "RECOMMENDED if `<chunk-index>` is used in filenames",
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 3ce1dbe347..4e1b800b49 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -10,6 +10,12 @@ JSON file is also REQUIRED.
 Each derivative type defines their own set of fields, but all of them
 share the following (non-required) ones:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
         "Description": (
@@ -89,6 +95,12 @@ If the [`space` entity](../99-appendices/09-entities.md#space) is omitted,
 or the space is not in the [Standard template identifiers][templates] table,
 then the `SpatialReference` metadata is REQUIRED.
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "SpatialReference": "RECOMMENDED if the derivative is aligned to a standard template listed in [Standard template identifiers][templates]. REQUIRED otherwise.",
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index cf394fa5a2..9e313de7b2 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -52,6 +52,12 @@ A guide for using macros can be found at
 
 The following metadata JSON fields are defined for preprocessed images:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "SkullStripped": "REQUIRED",
@@ -154,6 +160,12 @@ and the `Atlas` metadata SHOULD be defined.
 
 JSON metadata fields:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "RawSources": "REQUIRED",
@@ -229,6 +241,12 @@ Probabilistic segmentations of surfaces are currently [unspecified][].
 
 The following metadata fields apply to all segmentation files:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "Manual": "OPTIONAL",
diff --git a/src/99-appendices/11-qmri.md b/src/99-appendices/11-qmri.md
index a201904a14..a2f8b7883a 100644
--- a/src/99-appendices/11-qmri.md
+++ b/src/99-appendices/11-qmri.md
@@ -282,6 +282,12 @@ For example, without the information of `MagneticFieldStrength`, white-matter T1
 -   The JSON file accompanying a qMRI map which is obtained by using open-source software is RECOMMENDED
     to include additional metadata fields listed in the following table:
 
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_metadata_table(
    {
       "BasedOn": "RECOMMENDED",

From 1ebdae5da49c411dd73f2271cd30659acd5bd4b8 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:16:10 +0200
Subject: [PATCH 05/10] [DATALAD RUNCMD] add columns table macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_columns_table/i \\<!-- This block generates a columns table.\\nThe definitions of these fields can be found in\\n  src/schema/objects/columns.yaml\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 src/03-modality-agnostic-files.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index a8ae9db9b4..ff10fc9794 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -211,6 +211,12 @@ Commonly used *optional* columns in `participants.tsv` files are `age`, `sex`,
 of these columns, and in case that you do use them, we RECOMMEND to use the
 following values for them:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "participant_id": ("REQUIRED", "There MUST be exactly one row for each participant."),
@@ -290,6 +296,12 @@ The purpose of this file is to describe properties of samples, indicated by the
 This file is REQUIRED if `sample-<label>` is present in any filename within the dataset.
 Each sample MUST be described by one and only one row.
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "sample_id": ("REQUIRED", "The combination of `sample_id` and `participant_id` MUST be unique."),
@@ -432,6 +444,12 @@ Some recordings consist of multiple parts, that span several files,
 for example through `echo-`, `part-`, or `split-` entities.
 Such recordings MUST be documented with one row per file.
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "filename": ("REQUIRED", "There MUST be exactly one row for each file."),
@@ -475,6 +493,12 @@ These files MUST include a `session_id` column and describe each session by one
 Column names in `sessions.tsv` files MUST be different from group level participant key column names in the
 [`participants.tsv` file](./03-modality-agnostic-files.md#participants-file).
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "session_id": ("REQUIRED", "There MUST be exactly one row for each session."),

From b7d96021fede692c0c6dcaa83ae954c6e7bb8804 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:16:54 +0200
Subject: [PATCH 06/10] [DATALAD RUNCMD] add columns table macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_columns_table/i \\<!-- This block generates a columns table.\\nThe definitions of these fields can be found in\\n  src/schema/objects/columns.yaml\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 .../02-magnetoencephalography.md              | 12 ++++++++
 .../03-electroencephalography.md              | 24 +++++++++++++++
 .../04-intracranial-electroencephalography.md | 30 +++++++++++++++++++
 .../05-task-events.md                         | 12 ++++++++
 ...logical-and-other-continuous-recordings.md |  6 ++++
 .../09-positron-emission-tomography.md        |  6 ++++
 src/05-derivatives/03-imaging.md              |  6 ++++
 7 files changed, 96 insertions(+)

diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md
index 7ff5711635..f6df2ee748 100644
--- a/src/04-modality-specific-files/02-magnetoencephalography.md
+++ b/src/04-modality-specific-files/02-magnetoencephalography.md
@@ -261,6 +261,12 @@ The columns of the channels description table stored in `*_channels.tsv` are:
 
 MUST be present **in this specific order**:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "name__channels": "REQUIRED",
@@ -271,6 +277,12 @@ MUST be present **in this specific order**:
 
 SHOULD be present:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "description": "OPTIONAL",
diff --git a/src/04-modality-specific-files/03-electroencephalography.md b/src/04-modality-specific-files/03-electroencephalography.md
index 6567481ab4..1b4ce3763b 100644
--- a/src/04-modality-specific-files/03-electroencephalography.md
+++ b/src/04-modality-specific-files/03-electroencephalography.md
@@ -229,6 +229,12 @@ The columns of the channels description table stored in `*_channels.tsv` are:
 
 MUST be present **in this specific order**:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "name__channels": "REQUIRED",
@@ -239,6 +245,12 @@ MUST be present **in this specific order**:
 
 SHOULD be present:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "description": "OPTIONAL",
@@ -305,6 +317,12 @@ file MUST be specified as well**. The order of the required columns in the
 
 MUST be present **in this specific order**:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "name__electrodes": "REQUIRED",
@@ -316,6 +334,12 @@ MUST be present **in this specific order**:
 
 SHOULD be present:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "type__electrodes": "RECOMMENDED",
diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
index a3f3a9f0a9..6e351b818c 100644
--- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md
+++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
@@ -251,6 +251,12 @@ The columns of the channels description table stored in `*_channels.tsv` are:
 
 MUST be present **in this specific order**:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "name__channels": ("REQUIRED", "When a corresponding electrode is specified in `_electrodes.tsv`, "
@@ -265,6 +271,12 @@ MUST be present **in this specific order**:
 
 SHOULD be present:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "reference__ieeg": "OPTIONAL",
@@ -371,6 +383,12 @@ Units are specified in `space-<label>_coordsystem.json`.
 
 MUST be present **in this specific order**:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "name__electrodes": "REQUIRED",
@@ -383,6 +401,12 @@ MUST be present **in this specific order**:
 
 SHOULD be present:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "material": "RECOMMENDED",
@@ -394,6 +418,12 @@ SHOULD be present:
 
 MAY be present:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "type__electrodes": "OPTIONAL",
diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md
index fe192cbe81..a2599d35e1 100644
--- a/src/04-modality-specific-files/05-task-events.md
+++ b/src/04-modality-specific-files/05-task-events.md
@@ -34,6 +34,12 @@ file describing the columns in detail (see
 The tabular files consists of one row per event and a set of REQUIRED
 and OPTIONAL columns:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "onset": "REQUIRED",
@@ -147,6 +153,12 @@ for a given event,
 There are no restrictions on the file formats of the stimuli files,
 but they should be stored in the `/stimuli` folder.
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "stim_file": "OPTIONAL",
diff --git a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
index be739d38d7..06a90f3f3a 100644
--- a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
+++ b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
@@ -128,6 +128,12 @@ A guide for using macros can be found at
 To store pulse or breathing measurements, or the scanner trigger signal, the
 following naming conventions SHOULD be used for the column names:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "cardiac": "OPTIONAL",
diff --git a/src/04-modality-specific-files/09-positron-emission-tomography.md b/src/04-modality-specific-files/09-positron-emission-tomography.md
index c924fdd1a6..e96df1077f 100644
--- a/src/04-modality-specific-files/09-positron-emission-tomography.md
+++ b/src/04-modality-specific-files/09-positron-emission-tomography.md
@@ -401,6 +401,12 @@ and a guide for using macros can be found at
 The following columns are defined for `_blood.tsv` files.
 The `time` column MUST always be the first column.
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "time": "REQUIRED",
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 9e313de7b2..1b0fc9da47 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -519,6 +519,12 @@ A guide for using macros can be found at
 
 These TSV lookup tables contain the following columns:
 
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/objects/columns.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_columns_table(
    {
       "index": "REQUIRED",

From 76f04233fc3b2d2632251ba915c5139e2a72b78a Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:20:02 +0200
Subject: [PATCH 07/10] [DATALAD RUNCMD] add suffix macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_suffix_table/i \\<!--\\nThis block generates a suffix table.\\nThe definitions of these fields can be found in\\n  src/schema/rules/datatypes\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 .../01-magnetic-resonance-imaging-data.md     | 42 +++++++++++++++++++
 .../10-microscopy.md                          |  7 ++++
 2 files changed, 49 insertions(+)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 4914e80ef4..5e1371bd7b 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -250,6 +250,13 @@ whenever possible. See also
 
 Currently supported non-parametric structural MR images include:
 
+<!--
+This block generates a suffix table.
+The definitions of these fields can be found in
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_suffix_table(
       [
          "T1w",
@@ -371,6 +378,13 @@ different reconstruction algorithms (for example ones using motion correction).
 Structural MR images whose intensity is represented in a non-arbitrary scale
 constitute parametric maps. Currently supported parametric maps include:
 
+<!--
+This block generates a suffix table.
+The definitions of these fields can be found in
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_suffix_table(
       [
          "T1map",
@@ -416,6 +430,13 @@ They are, however, still valid suffixes, to maintain backwards compatibility.
 The following suffixes are valid, but SHOULD NOT be used for new BIDS compatible
 datasets (created after version 1.5.0.):
 
+<!--
+This block generates a suffix table.
+The definitions of these fields can be found in
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_suffix_table(
       [
          "T2star",
@@ -429,6 +450,13 @@ datasets (created after version 1.5.0.):
 
 Currently supported image contrasts include:
 
+<!--
+This block generates a suffix table.
+The definitions of these fields can be found in
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_suffix_table(
       [
          "bold",
@@ -683,6 +711,13 @@ and that can be used for practical guidance when curating a new dataset:
 Diffusion-weighted imaging data acquired for a participant.
 Currently supported image types include:
 
+<!--
+This block generates a suffix table.
+The definitions of these fields can be found in
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_suffix_table(
       [
          "dwi",
@@ -1092,6 +1127,13 @@ The current version of this standard considers four different scenarios:
 These four different types of field mapping strategies can be encoded
 using the following image types:
 
+<!--
+This block generates a suffix table.
+The definitions of these fields can be found in
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_suffix_table(
       [
          "magnitude",
diff --git a/src/04-modality-specific-files/10-microscopy.md b/src/04-modality-specific-files/10-microscopy.md
index 103dbc9092..77d4598524 100644
--- a/src/04-modality-specific-files/10-microscopy.md
+++ b/src/04-modality-specific-files/10-microscopy.md
@@ -57,6 +57,13 @@ as a successor to OME-TIFF for better remote sharing of large datasets.
 ### Modality suffixes
 Microscopy data currently support the following imaging modalities:
 
+<!--
+This block generates a suffix table.
+The definitions of these fields can be found in
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_suffix_table(
       [
          "TEM",

From b6db15828195cce2ab4e39afbddffa1b610c550d Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:21:52 +0200
Subject: [PATCH 08/10] [DATALAD RUNCMD] add filename template macro comment

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "sed -i '/^.*make_filename_template/i \\<!--\\nThis block generates a filename templates.\\nThe inputs for this macro can be found in the folder\\n  src/schema/rules/datatypes\\nand a guide for using macros can be found at\\n https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md\\n-->' ./src/**/*.md",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 .../01-magnetic-resonance-imaging-data.md     | 56 +++++++++++++++++++
 .../02-magnetoencephalography.md              | 35 ++++++++++++
 .../03-electroencephalography.md              | 35 ++++++++++++
 .../04-intracranial-electroencephalography.md | 35 ++++++++++++
 .../07-behavioral-experiments.md              |  7 +++
 .../09-positron-emission-tomography.md        | 14 +++++
 .../10-microscopy.md                          | 14 +++++
 src/99-appendices/10-file-collections.md      | 14 +++++
 8 files changed, 210 insertions(+)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 5e1371bd7b..149790ea38 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -246,6 +246,13 @@ whenever possible. See also
 
 ## Anatomy imaging data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["anat"]) }}
 
 Currently supported non-parametric structural MR images include:
@@ -466,6 +473,13 @@ and a guide for using macros can be found at
    )
 }}
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["func"]) }}
 
 Functional imaging consists of techniques that support rapid temporal repetition.
@@ -726,6 +740,13 @@ and a guide for using macros can be found at
    )
 }}
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["dwi"]) }}
 
 If more than one run of the same acquisition and direction has been acquired, the
@@ -943,6 +964,13 @@ Several [example ASL datasets](https://github.com/bids-standard/bids-examples#as
 have been formatted using this specification
 and can be used for practical guidance when curating a new dataset.
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["perf"]) }}
 
 The complete ASL time series should be stored as a 4D NIfTI file in the original acquisition order,
@@ -1217,6 +1245,13 @@ containing that type of fieldmap can be found here:
 -   [`genetics_ukbb`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
 -   [`ds000117`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["fmap"], suffixes=["phasediff", "magnitude1", "magnitude2"]) }}
 
 where
@@ -1259,6 +1294,13 @@ Similar to case 1, but instead of a precomputed phase-difference map, two
 separate phase images and two magnitude images corresponding to first and
 second echos are available.
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["fmap"], suffixes=["phase1", "phase2", "magnitude1", "magnitude2"]) }}
 
 Required fields:
@@ -1289,6 +1331,13 @@ For example, `sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json`
 In some cases (for example GE), the scanner software will directly reconstruct a
 *B<sub>0</sub>* field map along with a magnitude image used for anatomical reference.
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["fmap"], suffixes=["fieldmap", "magnitude"]) }}
 
 Required fields:
@@ -1337,6 +1386,13 @@ in the latter case, all timepoints share the same scanning parameters.
 Examples of software tools using these kinds of images are FSL TOPUP,
 AFNI `3dqwarp`, and SPM.
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["fmap"], suffixes=["epi"]) }}
 
 The [`dir-<label>`](../99-appendices/09-entities.md#dir) entity is REQUIRED
diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md
index f6df2ee748..4f270f5661 100644
--- a/src/04-modality-specific-files/02-magnetoencephalography.md
+++ b/src/04-modality-specific-files/02-magnetoencephalography.md
@@ -16,6 +16,13 @@ the [BIDS examples repository](https://github.com/bids-standard/bids-examples).
 
 ## MEG recording data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(
    datatypes=["meg"],
    suffixes=["meg", "markers", "events", "physio", "stim"])
@@ -249,6 +256,13 @@ Date time information MUST be expressed as indicated in [Units](../02-common-pri
 
 ## Channels description (`*_channels.tsv`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["meg"], suffixes=["channels"]) }}
 
 This file is RECOMMENDED as it provides easily searchable information across BIDS datasets.
@@ -355,6 +369,13 @@ UADC001 AUDIO V envelope of audio signal presented to participant
 
 ## Coordinate System JSON (`*_coordsystem.json`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["meg"], suffixes=["coordsystem"]) }}
 
 OPTIONAL. A JSON document specifying the coordinate system(s) used for the MEG,
@@ -499,6 +520,13 @@ or:
 Photos of the anatomical landmarks and/or head localization coils
 (`*_photo.jpg`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["meg"], suffixes=["photo"]) }}
 
 Photos of the anatomical landmarks and/or head localization coils on the
@@ -519,6 +547,13 @@ actual anatomical nasion: `sub-0001_ses-001_acq-NAS_photo.jpg`
 
 ## Head shape and electrode description (`*_headshape.<ext>`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["meg"], suffixes=["headshape"]) }}
 
 This file is RECOMMENDED.
diff --git a/src/04-modality-specific-files/03-electroencephalography.md b/src/04-modality-specific-files/03-electroencephalography.md
index 1b4ce3763b..95bdeb7850 100644
--- a/src/04-modality-specific-files/03-electroencephalography.md
+++ b/src/04-modality-specific-files/03-electroencephalography.md
@@ -12,6 +12,13 @@ and can be used for practical guidance when curating a new dataset.
 
 ## EEG recording data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(
    datatypes=["eeg"],
    suffixes=["eeg", "events", "physio", "stim"])
@@ -209,6 +216,13 @@ Date time information MUST be expressed as indicated in [Units](../02-common-pri
 
 ## Channels description (`*_channels.tsv`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["eeg"], suffixes=["channels"]) }}
 
 This file is RECOMMENDED as it provides easily searchable information across BIDS datasets.
@@ -306,6 +320,13 @@ UADC001  MISC  n/a    envelope of audio signal        n/a           good    n/a
 
 ## Electrodes description (`*_electrodes.tsv`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["eeg"], suffixes=["electrodes"]) }}
 
 File that gives the location of EEG electrodes. Note that coordinates are
@@ -370,6 +391,13 @@ the recording.
 
 ## Coordinate System JSON (`*_coordsystem.json`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["eeg"], suffixes=["coordsystem"]) }}
 
 A `*_coordsystem.json` file is used to specify the fiducials, the location of
@@ -502,6 +530,13 @@ Example:
 
 Photos of the anatomical landmarks and/or fiducials.
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["eeg"], suffixes=["photo"]) }}
 
 Photos of the anatomical landmarks and/or fiducials are OPTIONAL.
diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
index 6e351b818c..c79742abaa 100644
--- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md
+++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
@@ -12,6 +12,13 @@ and can be used for practical guidance when curating a new dataset.
 
 ## iEEG recording data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(
    datatypes=["ieeg"],
    suffixes=["ieeg", "events", "physio", "stim"])
@@ -235,6 +242,13 @@ Date time information MUST be expressed as indicated in [Units](../02-common-pri
 
 ## Channels description (`*_channels.tsv`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["ieeg"], suffixes=["channels"]) }}
 
 A channel represents one time series recorded with the recording system
@@ -333,6 +347,13 @@ Example of free-form text for field `description`:
 
 ## Electrode description (`*_electrodes.tsv`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["ieeg"], suffixes=["electrodes"]) }}
 
 File that gives the location, size and other properties of iEEG electrodes. Note
@@ -443,6 +464,13 @@ H01   27  -42  -21  5      AdTech
 
 ## Coordinate System JSON (`*_coordsystem.json`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["ieeg"], suffixes=["coordsystem"]) }}
 
 This `_coordsystem.json` file contains the coordinate system in which electrode
@@ -538,6 +566,13 @@ Example:
 
 ## Photos of the electrode positions (`*_photo.jpg`)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["ieeg"], suffixes=["photo"]) }}
 
 These can include photos of the electrodes on the brain surface, photos of
diff --git a/src/04-modality-specific-files/07-behavioral-experiments.md b/src/04-modality-specific-files/07-behavioral-experiments.md
index e0a1ec2946..fe55de93bf 100644
--- a/src/04-modality-specific-files/07-behavioral-experiments.md
+++ b/src/04-modality-specific-files/07-behavioral-experiments.md
@@ -1,5 +1,12 @@
 # Behavioral experiments (with no neural recordings)
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["beh"]) }}
 
 In addition to logs from behavioral experiments performed alongside imaging data
diff --git a/src/04-modality-specific-files/09-positron-emission-tomography.md b/src/04-modality-specific-files/09-positron-emission-tomography.md
index e96df1077f..e7661be71b 100644
--- a/src/04-modality-specific-files/09-positron-emission-tomography.md
+++ b/src/04-modality-specific-files/09-positron-emission-tomography.md
@@ -60,6 +60,13 @@ In this example, tracer injection coincides with scan start.
 
 ## PET recording data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(
    datatypes=["pet"],
    suffixes=["pet", "events", "physio", "stim"])
@@ -339,6 +346,13 @@ ses-02 59
 
 ## Blood recording data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["pet"], suffixes=["blood"]) }}
 
 If collected, blood measurements of radioactivity are be stored in
diff --git a/src/04-modality-specific-files/10-microscopy.md b/src/04-modality-specific-files/10-microscopy.md
index 77d4598524..60cac4cd3f 100644
--- a/src/04-modality-specific-files/10-microscopy.md
+++ b/src/04-modality-specific-files/10-microscopy.md
@@ -18,6 +18,13 @@ Further Microscopy datasets are available:
 
 ## Microscopy imaging data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["micr"], suffixes=["TEM", "SEM", "uCT", "BF", "DF",
 "PC", "DIC", "FLUO", "CONF", "PLI", "CARS", "2PE", "MPE", "SR", "NLO", "OCT", "SPIM"], n_dupes_to_combine=4) }}
 
@@ -456,6 +463,13 @@ Photos of the tissue sample, overview microscopy scans or blockface images from
 MAY be included for visualization of large samples or to indicate the location of chunks
 in a sample.
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(datatypes=["micr"], suffixes=["photo"], n_dupes_to_combine=3) }}
 
 The file `<extension>` for photos MUST be either `.jpg`, `.png` or `.tif`.
diff --git a/src/99-appendices/10-file-collections.md b/src/99-appendices/10-file-collections.md
index 004c2a33dd..ce95bd8146 100644
--- a/src/99-appendices/10-file-collections.md
+++ b/src/99-appendices/10-file-collections.md
@@ -22,6 +22,13 @@ included in this appendix:
 
 ### Anatomy imaging data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(
     datatypes=["anat"],
     suffixes=[
@@ -49,6 +56,13 @@ included in this appendix:
 
 ### Fieldmap data
 
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the folder
+  src/schema/rules/datatypes
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filename_template(
     datatypes=["fmap"],
     suffixes=[

From 07c88317ee07a15098c8ed201ed4e26382a5afc4 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:24:22 +0200
Subject: [PATCH 09/10] update other macros with comments

---
 src/99-appendices/04-entity-table.md | 2 ++
 src/99-appendices/09-entities.md     | 2 ++
 src/99-appendices/14-glossary.md     | 2 ++
 3 files changed, 6 insertions(+)

diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index 3056eb326d..de13336818 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -16,6 +16,8 @@ while entity definitions are in [Appendix IX](09-entities.md).
 <!--
   This file is autogenerated based on the src/schema.  DO NOT EDIT DIRECTLY.
   Follow https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#making-a-change-to-the-bids-schema
+  and a guide for using macros can be found at
+  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 
 ## Magnetic Resonance Imaging
diff --git a/src/99-appendices/09-entities.md b/src/99-appendices/09-entities.md
index 64d9700033..1f63bc707e 100644
--- a/src/99-appendices/09-entities.md
+++ b/src/99-appendices/09-entities.md
@@ -12,5 +12,7 @@ be specified for a given file type, is specified in the [Entity Table](04-entity
 <!--
   This section is autogenerated based on the src/schema.  DO NOT EDIT DIRECTLY.
   Follow https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#making-a-change-to-the-bids-schema
+  and a guide for using macros can be found at
+  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 {{ MACROS___make_entity_definitions() }}
diff --git a/src/99-appendices/14-glossary.md b/src/99-appendices/14-glossary.md
index 8f9affb6f1..97f89e98dd 100644
--- a/src/99-appendices/14-glossary.md
+++ b/src/99-appendices/14-glossary.md
@@ -5,5 +5,7 @@ This section compiles the object definitions in the schema.
 <!--
   This section is autogenerated based on the src/schema.  DO NOT EDIT DIRECTLY.
   Follow https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#updating-the-schema
+  and a guide for using macros can be found at
+  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 {{ MACROS___make_glossary() }}

From 3063ec2a7c09417ce355a7dcbd6f3bad955b4c22 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Sun, 3 Apr 2022 08:33:10 +0200
Subject: [PATCH 10/10] indent comment

---
 src/02-common-principles.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index fd54ad1a20..ebef54135b 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -362,10 +362,10 @@ Derivatives can be stored/distributed in two ways:
 
     Example of a derivative dataset including the raw dataset as source:
 
-<!-- This block generates a file tree.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
+    <!-- This block generates a file tree.
+    A guide for using macros can be found at
+    https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+    -->
     {{ MACROS___make_filetree_example(
         {
         "my_processed_data": {