Skip to content

Documentation Convention

In public documentation, we strive to adhere to consistent principles to maintain a coherent structure for describing our products. Work on the convention is still ongoing.

Check before publishing

Documentation is published automatically when merged into the main branch. Therefore, before merging a pull request, please check locally that

  • all links work
  • all images/icons are displayed
  • the documentation is easy to read
  • it adheres to accepted conventions
  • you like it
How to set up a local preview?

You'll need to install Material for MKDocs and some plugins:

pip install mkdocs-material
pip install mkdocs-minify-plugin
pip install mkdocs-include-markdown-plugin

After that, in the root of your repository clone, simply run

mkdocs serve

In the console you will see something like 

INFO    -  [10:46:26] Serving on http://127.0.0.1:8000/
Open this link and check it out.

External

New tab/window

Always add {:target="_blank"}

for an external link to open it in a new tab or window

Visual mark

Always visually mark links that lead outside the documentation site. There are two options:

Add this icon to the end of the link title

:octicons-link-external-24:

Example

[aiuta.com :octicons-link-external-24:](https://aiuta.com){:target="_blank"}

aiuta.com

When grouping links into blocks with grid cards you can omit the icon if you use an explicit action in the link title, such as "Open", "Download", etc.

Example

<div class="grid cards" markdown>

- :fontawesome-brands-google-play: [Get it on __Google Play__](https://play.google.com/store/apps/details?id=com.aiuta.fashionsdk.demo){:target="_blank"}
- :fontawesome-brands-shopify: [View in the __Shopify__ app store](https://shopify.aiuta.com){:target="_blank"}

</div>

Internal

This leads to the same result but is easier to maintain in the future.

Root is /docs

[About SDK](/sdk/)

![img](/media/about.png){ width=100 }
About SDK

img 

[About SDK](../../sdk/index.md)

![img](../../media/about.png){ width=100 }
About SDK

img

Custom doc admonition

If you want to specifically highlight links as references to other parts of the documentation, use a custom doc admonition that has some special style settings

Example

!!! doc "To understand this, see [that](#)"

To understand this, see that

Example

!!! doc "For full context, see"

    - [this](#)
    - maybe [that](#)
    - and something [more](#)

For full context, see

Sources

Always provide links to sources and packages, if available, giving preference to grid cards .

Example

<div class="grid cards" markdown>

- :fontawesome-brands-flutter: [Pub.dev package :octicons-link-external-24:](https://pub.dev/packages/aiuta_flutter){:target="_blank"}
- :fontawesome-brands-github: [Plugin sources :octicons-link-external-24:](https://github.com/aiuta-com/flutter-sdk){:target="_blank"}

</div>

Code blocks

Instead of comments, give preference to annotations , which can be much more detailed and contain active links, images, and instructions. Describe things in detail, keeping the code clean and free of comments. Don't forget to specify default values in the example admonition , if applicable.

Example

``` typescript
Foo {
  bar: Bar // (1)!
}
```

1.  Here is annotaion with [link](#), image

    ![image](/media/images/imagePickerSample1.png){ width=50 }

    !!! example ""
        and default value


Foo {
  bar: Bar // (1)!
}

  1. Here is annotaion with link, image

    image

    and default value

Schemes

To describe a language-independent scheme or data model use a code block with typescript highlighting where

  • omit key constructs such as class, new, etc., that are redundant for the description
  • avoid traling commas and semicolons, as well as colons between property definitions and opening brackets, cluttering up the scheme
  • prefer PascalCase for types and camelCase for properties (1)
  • define collections as List<> and Map<>
  • denote enumerated / sealed types with |, combined with tabs for their schemes
  • indicate optional fields with | null
  • indent with 2 spaces
  1. except for the API, which uses snake_case

Example

``` typescript
Foo {
  fooProperty1: String
  fooProperty2: Number | null
  fooProperty3: Bar1 | Bar2 | null

  fooEmbeddedeType {
    fooEmbeddedeTypeProperty1: String
  }
}
```

=== "Bar1"
    ``` typescript
    Bar1 {
      bar1Property1: List<Bool>
    }
    ```

=== "Bar2"
    ``` typescript
    Bar2 {
      bar2Property1: Map<String, Bool>
    }
    ```    

Foo {
  fooProperty1: String
  fooProperty2: Number | null
  fooProperty3: Bar1 | Bar2 | null

  fooEmbeddedeType {
    fooEmbeddedeTypeProperty1: String
  }
}


Bar1 {
  bar1Property1: List<Bool>
}

Bar2 {
  bar2Property1: Map<String, Bool>
}

Templates

If several pages of your documentation contain identical sections regarding repetitive reminders, a list of some questions, or system requirements, please create templates and include them with the include-markdown

Example

% instead of #. Careful, it works even inside code blocks.

{# include-markdown "sdk/templates/flutter/requirements.md" %}


sdk: >=3.1.0 <4.0.0
flutter: >= 3.19.6

Appearance

Keep documentation clean, uncluttered, divided into sections, use visual indicators to draw attention to specific areas (icons, admonitions, grid cards mentioned earlier).

Dark theme

Let's respect people who prefer dark themes

  • provide a contrasting alternative for monochrome images that cannot be colored, add #only-light or #only-dark at the end of the resource path
  • define a contrasting background with stylesheets/aiuta.css for anything that has no alternative in the dark version

Example

<!-- good in both themes -->

:material-format-color-text:{ .cl-aiuta }
![back24](/media/icons/back24.png#only-light){ width=12 } 
![back24](/media/icons/on-dark/back24.png#only-dark){ width=12 }
![close24](/media/icons/close24.png#only-light){ width=12 } 
![close24](/media/icons/on-dark/close24.png#only-dark){ width=12 }

<!-- bad in a dark theme  -->

:material-format-color-text:{ .cl-selection-background }
![back24](/media/icons/back24.png){ width=12 }
![close24](/media/icons/close24.png){ width=12 }

.cl-aiuta {
  color: #4000FF;
}

/* Light background for dark colors to contrast */
.cl-primary,
.cl-aiuta {
  background-color: #FFFFFF;
  border-radius: 6px;
}

back24 back24 close24 close24

back24 close24

Swich docs to a dark theme using / toggle in the header to see the difference

Custom icons

If you need a special icon, you couldn't find a suitable one among the huge number available icons , and want to export yours from Figma and place it in the overrides/.icons directory, please edit the exported svg file manually, replacing the fill color (usually white or black for icons) with the currentColor to match current typeface color.

Example

<svg width="29" height="29" viewBox="0 0 29 29" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="29" height="29" rx="4" fill="white"/>
</svg>

<svg width="29" height="29" viewBox="0 0 29 29" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="29" height="29" rx="4" fill="currentColor"/>
</svg>

In the current version of Figma, you can set the currentColor as a value but it will unfortunately be replaced with some explicit color, probaly #CCCCCC

How to use custom icons?

Custom icons, which are located in the overrides/.icons directory, will be available to use by putting the valid path between two colons, and replacing / with -

Example

:aiuta-logo: :aiuta-favicon:

Common sense

Use it.