@cake-hub/showroom v0.0.0-alpha.8

CAKE Showroom (CLI)

This package manages different project documentations and merges them together into one documentation website. We support different features like changelogs, examples included in your documentation. Basically you can configure some settings for each project and write in each project it's own documentation with simple markdown files. We've just improved the markdown syntax with some special components and syntax which will make your documentations even more powerful.

Installing

To install this package simply run

npm install --save @cake-hub/showroom

or to install this package even globally just run

npm install -g @cake-hub/showroom

CLI commands

This package provides some powerful cli commands that you can use. If you have this package globally installed you can simply run @cake-hub/showroom <command> <attributes*> or if it was only installed into your project, you have to run npx @cake-hub/showroom <command> <attributes>.

List of commands

• start: simply build the documentations and startup server
• server: startup a server for serving the documentation
• dev: builds the documentation on the fly triggerd by changes and starts up a development server
• build: only build the documenation
• release: another name for the build command
• symlinks: correctly references all the documentation folders to prepare build
• build-projects: runs the build command of all project configurations (see project.yml)
• build-assets: builds the asset for the documentation
• build-docs: converts the documentation markdown files to beautiful html files
• watch-assets: watches only the documentation assets and rebuilds them on changes
• watch-docs: watches the documentation files of your projects and rebuilds them on changes

Example usage

Simply build the documentation to static html (+asset) files:

npx @cake-hub/showroom build

Startup the development server to actively work on the project documentations and to get direct visible feedback:

npx @cake-hub/showroom dev

Configuration file

We set up some default configuration for you to give you an easy kick start. To also support matured projects with more complex requirements we do provide you the functionality to set up your own configuration file to overwrite these default settings. The configuration file needs to be in root folder of your package and requires the name cake-showroom.yml. You can use any of the following keys to change the settings, but you can also skip the values that are just fine for you!

environment: production # indicates development and production environment

build:
  destinationPath: ./docs # the output folder of the compiled documentation
  hiddenPrefixes: # the prefixes of the folders that should not be put into the compiled showroom
    - "."
    - "_"
  hiddenFolders: # folders that should not be published at all
    - _assets

projects:
  folderPath: ./projects # the root folder of all your projects you want to publish
  configurationfileName: project.yml # the name of the configuration file
  navigationFileName: nav.yml # the name of the navigation configuration file

tracking:
  googleTagManagerId: XXX # optional goolge-tag-manager id for tracking
  cookiebotDomainGroupId: XXX # optional cookiebot id for fulfilling GDPR requirements

server:
  port: 2020 # the port of the server

changelogs:
  categories: # all available changelog categories that can be used
    - Highlights
    - Added
    - Changed
    - Deprecated
    - Removed
    - Fixed
    - Security
  pageIdentifier: _changelog.md # the component specific changelog-file name
  summaryIdentifier: _changelog-general.md # the summary changelog-file name
  menuIdentifier: Change log.md # the placeholder file name to put the summary changelog into the menu

The values above are the default values for each key.

Project interface

To prepare your project to the CAKE showroom there is not needed that much. The CAKE showroom does work with any project independet of the technology-stack, language, purpose, …. So any project can be published to the community. The only thing that is needed: a documentation.

First of all you need an additional folder that holds anything that is required by your documentation. For example you could simply create a ./docs folder in the root of your project.

project.yml

The first and only requirement besides your documentation is the project.yml file. This is needed to set up some basic information and configuration of your project and how it will be shown in the CAKE showroom. Your project.yml file could look like the following example. So basically it is a very simple yaml-file with different key-value pairs and some more complex options to provide more functionality.

version: 1.0.0-beta.2 # your actual version of the project / documentation
designLine: Apple Pie # an overall design line for your brand
company: Lidl # The brand your project assigned to
product: Mail # the product category your project is assigned to
productIcon: earth # the icon of the product category
section: Design # the actual name of your project
sectionIcon: code # the icon for your project
build: cd ../ && npm install && npm run build # the build-command that get's executed in your projects root folder just before the documentation gets created *optional*
develop: cd ../ && npm run dev # the development-command that get's executed when starting the @cake-hub/showroom dev command *optional*
hiddenFiles: # list files that should not be made public but are placed in your documentation folder (without leading '/' or './') *optional*
  - config.yml
  - some-other-file.js
  - some/deeper/file.java
variables: # define a more complex object to provide dynamic variable values that can be used in the documentation markdown files *optional*
    someVar: someValue

Documentation structure

Even if the structure of the documentation is almost completely up to you, some basic folders or elements are required. As already mentioned the project.yml needs to be in the root of your documentation folder. Also the optional nav.yml file is required to be in the root directory, if it is required at all. Additionaly you have to put every documentation page inside a category. And this category is defined by the root-level folder. Inside this category-folder you can completely structure the documentation in the way you like. You can add some asset-folders, structure the markdown file inside some deep hierarchy. At the end each markdown-file inside a category-folder will be displayed just inside this category.

Important to mention is, that the naming of the menu points will be directly derived from the folder- and file-names. So make sure to use some appropriate namings here.

./docs
├── project.yml
├── nav.yml # *optional*
├── Category 1
    ├── Page 1.md
    ├── Page 2.md
    └── Page 3.md
├── Category 2
    ├── Page 1.md
    ├── Page 2
        ├── Page 2.md
        ├── image1.jpg
        └── another_asset.html
    └── Page 3.md
├── Category 3
    └── …
├── Category 4
    └── …
└── …

Be careful putting your files inside the documentation folder, because everything that is not excluded from the configuration (hidden-prefixes, hidden folders) get's published and made available through the internet!

Navigation structure

The menu of the CAKE showroom will be shown in alphabetical order. This is not always the best structure for your documentation. As we know this problem you have the possibility to restructure/reorder your menu with the nav.yml file. With this file you can actively configure the order of the menu.

In the following example you can see how to move the category Category 2 just above Category 1. The same thing can of course be done with the pages inside the category by providing the pages property.

- path: ./Category 2
  pages:
    - path: ./Site2/Site2.md
    - path: ./Site1.md
    - path: /Site3/text/Site3.md
- path: ./Category 1

Everything not mentioned in the nav.yml file will be appended automatically, again in ascending alphabetical order.

Markdown syntax

As the file extension suggests, the documentations are written in plain markdown syntax. As the default markdown features does not support more complex documentations, we've added some functionality to this syntax. These additions will be explained in the following paragraphs.

Headlines

Like in every markdown file you can link to other headlines in the same or in other markdown-files by using anchor links. Only the level 1 headlines are not linkable. But there is one addition in our documentation markdown-files. In order to link to another headline you must prefix all parent headings h2-h3-… (expect h1) to the default anchor name:

# Headline one

Some example content...

## Headline two

Some more content...

### Headline three

Now i can link to the second headline with [this link](#headline-two).
Or link to an even deeper headline with [this link](#headline-two-headline-three).

With this way of linking headlines there is no problem with the same naming of different headline. Each headline can be uniquely identified by the anchor name with the additional headline-prefix(es).

Variables

As already mentioned, you can define some custom variables but you can also use all the default keys of your project.yml file inside your markdown files.

# Some headline of product {{ product }} | {{ company }}

Some text with version: {{ version }}.
{{ variables.someVar }}: {{ variables.otherVar }}

Web native assets

You can use the default markdown syntax to add your basic examples in the documentation. Therefore all native markdown file types are allowed plus some additional content shown in the example below.

![AlertDefault](examples/AlertDefault.jpg)
![AlertDefault](examples/AlertDefault.png)
# addition to default Markdown functionality are the following content types available
![AlertDefault](examples/AlertDefault.html)
![AlertDefault](examples/AlertDefault.mp4)

By using the default markdown syntax, the HTML example get's added as an <iframe> that resizes itself to the content of the HTML file. But if you need some advanced configurations, you can use the <Iframe> element (first letter uppercase), which internally uses also the native iframe component but you can add some more configuration that you need in your example.

<Iframe src="examples/ToTopPosition.html" scrolling="yes" style="min-height: 23rem" title="Position" alt="ToTopPosition" />

Alerts

To highlight some important information you can use one of the following two alerts: AlertInfo and AlertWarning.

<AlertInfo alertHeadline="Modifiable">
Please ensure to comply with the corporate identity.
</AlertInfo>

<AlertWarning alertHeadline="Not modifiable">
 It is mandatory to maintain the appearance and behavior of these components.
</AlertWarning>

Content-rack

This is a special component, you can use for extending the functionality of your documentation. Here you add functionalities like preview of source-code or links to other sources. Mostly this component is used above example previews. But you can use it anywhere in your documentation text.

<ContentRack
    fields='
        "online-docs": {
            "src": "http://www.google.de",
            "type": "link"
        },
        "source-code": {
            "src": "../example.html",
            "type": "content"
            "selector": "#some-element-id"
        },
        "download file": {
            "src": "../link/file-to-download.sketch",
            "type": "download"
        }
    '
/>

We recommend to use the short string notation. Otherwise there could be errors building the documentation. Line breaks are only possible in a limited way.

If you use heavy configurations in your <ContentRack> you can outsource the configuration to the content-rack.yml file. This is useful, if you want to keep your markdown file clean and not overloaded by the configurations of the Content-rack. To use this configuration file, you need the name="…" attribute and use this name as list-identifier in your yml file. Below you see an example of the content-rack.yml file, that has the same configuration then the above example.

- AlertDefault:
  fields:
    - <html>:
      selector: '#app' #only use the element as html
      src: example/AlertDefault.html #adjust syntax highlighting
      active: true #expand this content initially on page load (default: false)
    - online-docs:
      type: link
      src: ../link

Here is a example that points to the AlertDefault configuration options inside the content-rack.yml.

<ContentRack name="AlertDefault" />

You can use the configuration file instead or additional to the <ContentRack /> properties. Different properties are getting merged. Same properties will be overwritten by the values of the <ContentRack /> configurations.

Cross-linking

You can link to any source available in the internet with the default markdown link syntax:

[Some link to lidl.de](https://lidl.de)

To reference to documentation pages of the same project simply reference to the markdown page to be linked to. You simply use the relative path to the correct file:

[other documentation page](../../Components/Alert/Alert.md)

The switch of file extensions and all relevant changes will be done automatically by the build process of the showroom.

If you want to do cross linking between projects, you could create relative links like above to the correct markdown-file of the other project. To make this even more intuitive you are also able to use an absolute link and simply start from the root of the showroom path. You can then navigate to the appropriate project and file:

[other project: relative link](../../../../Web/Develop/Components/Alert/Alert.md)
[other project: absolute link](/Web/Develop/Components/Alert/Alert.md)

Changelogs

An additional feature of the CAKE showroom are the changelogs. You can add changelogs on a page level but also some general changelog entries that are not related to a specific page.

To add changelog entries to a single page, simply create a _changelog.md file into the same directory as the markdown page is. On building the CAKE showroom the content of this changelog-file get's automatically appended to the documentation page.

# Change log

## Version 1.0.0

### Highlights

* `Added`: **Footer**-Component
* `Changed`: Increased the `spacer` variable from .5rem to .1rem
* …

### Added

* `CSS`: New utility class for XXX
* `JS`: Added
* `Doc`: "To top" | Added spacing information between "To top" button and "Footer" components.

### Changed

* `HTML`, `CSS`: renamed `.alerts`-classes to `.alert`
* `Env`: Update npm package URL from `schwarzit.pkgs.visualstudio.com` to `pkgs.dev.azure.com/schwarzit`

### Deprecated

* …

All available headlines are listed in the changelogs.categories list. You can also add your additional headlines in the cake-showroom.yml configuration, if these are not enough.

Additionally you can create a _changelog-general.md file which contains all changes that are not related to one single page but the whole project. The structure is the same as for the _changelog.md files.

To preview a summary changelog in your rendered documentation simply add the Change log.md file at that position this page should be shown at. This file should be kept empty at all time, because the content will be ignored and overwritten. The content for this file will be automatically merged from all _changelog.md files and the _changelog-general.md file.