Marfeel Docs

# Architecture

This article describes MarfeelDocs extension architecture. How it is organized and where to add new content.

# Documents location

Documents must be next to the module they describe, in a docs folder. The exact location depends, whether the repository is a mono-repo or contains only one project.

For mono-repos, place the docs folder inside the module, but no deeper:

  • Gutenberg/MarfeelWonderlandDomain/docs/inventory/placement.md
  • Gutenberg/MarfeelGutenberg/docs/MarfeelAlibaba/phantomjs.md

For single-project repositories:

  • CMP/docs
  • MarfeelPress/docs
  • MarfeelSchemas/docs/metrics-catalog.md

MarfeelPlatform

MarfeelPlatform (opens new window) is a special, docs-only repository. It should only contain articles describing systems belonging to several repositories.

For example, Metrics extensions at Marfeel could equally be in Gutenberg or MarfeelXP. However, within Metrics extensions at Marfeel, it is clear that the catalog of extensions belongs to MarfeelSchemas. Read more on how to manage files from multiple sources in the sidebar.

# Folder structure

Every source code repository has a docs folder with the structure below to host the different supported types of documents

Repository
│
├─── README.md
├─── docs
│   │   quickstart.md
│   │   references.md
│   ├─── SDK Reference
│   │   └──── configuration.md
│   ├─── development
│   │   ├──── README.md
│   │   ├──── configuration.md
│   │   └──── references.md
│   ├─── alarms
│   │   ├──── alarms_1.md
│   │   └──── alarms_2.md
│   └─── guides
│       ├──── guide_1.md
│       └──── guide_2.md
└── sections.json

The first-level navigation options of MarfeelDocs is configured through the navigation.json file of the MarfeelDocs git repository (opens new window).

Through the main navigation.json different projects can be linked to the main MarfeelDocs sidebar. The second level options of the sidebar must be declared on the project-specific sections.json file. An example can be seen on the MarfeelDocs repository (opens new window)

navigation.json and sections.json allows us to force a given order of the menu options. It's also important to highlight that only markdown files referenced on the sections.json will appear on the sidebar.

The content of the sections.json file will typically look like this:

{
  "links": [
    "/", // README.md within or next to docs folder
    "/quickstart",
    "/references",
    "/development/", // README.md within development folder
    "/development/quickstart",
    "/development/contributing",
    "/development/guides/how_to_add_new_sub_projects"
  ]
}

# External files

To include an external file, the complete path has to be added to sections.json file like the following example:

{
  "links": [
    "/",
    "/metrics-json",
    "/metrics-leroy",
    {
      "path": "/metrics-catalog",
      "origin": "MarfeelSchemas/json-lint/docs/metrics-catalog.md"
    },
    "/metrics-how-to-create"
  ]
}

The assets folder next to the markdown origin file will also be copied, allowing you to use images in external files.

WARNING

All the repositories used have to be added in the .gitmodules file. (opens new window). See how to add subprojects guide.

# Implicit files

It is possible to include external files to a section without showing them in the sidebar.

Add the file to the inline array of sections.json:

{
  "links": [
    "/",
    "/metrics-json"
  ],
  "inline": [
    {
      "path": "/metrics-iframe",
      "origin": "Gutenberg/MarfeelGutenberg/docs/MarfeelBoilerpipe/providers-iframe.md"
    },
  ]
}

Usage

Implicit files are useful for very specific articles that don't add value on the sidebar.

For example, the WhiteCollar items article, which is only accessible via deeplinking or from the WhiteCollar main article.

The assets folder next to the markdown origin file will also be copied, allowing you to use images in implicitly added files.

TIP

This is only necessary for external files. All the markdown files in the docs folder of a repository are already compiled in MarfeelDocs.

# Monorepos

To use all the markdown files of a package part of a monorepository, the navigation.json accepts a packcage attribute too.

For example:

{
  "title": "Instrumentation",
  "repository":"flowcards",
  "uri": "/flowcards/track",
  "package": "instrumentation"
}

This section picks up the instrumentation docs of the flowcards repository, which is expected to be at flowcards/packages/instrumentation/docs following the lerna convention Marfeel uses.

Those files are then put in the flowcards/track folder, and that will be their final URL.

← Contributing →