This article is shared by @Xu Haifeng, head of Product development at Worktile



On May 20, 2021, Docgeni officially announced that it was open source. Check out Docgeni, the Angular component documentation tool out of the box. After more than four months, Docgeni is also slowly growing. So let’s take a closer look at what’s new in 1.1.0.

If you haven’t followed Docgeni yet, you can go to github.com/docgeni/doc… A Star.

Docgeni.org

1.1.0 Update inventory

New features

  • Custom home page function in full mode

  • Customize the Footer function

  • Document directory (toc) support for multiple representations (content | menu | hidden)

  • The component supports label presentation, including new, Deprecated, and experimental by default

  • New label, Alert, and Embed built-in components embedded via Markdown extension syntax

  • Support for custom built-in components embedded through Markdown extension syntax

  • The bottom of the document shows GitHub contributors and when they were last updated

  • The previous and next articles are shown at the bottom of the document

  • The component sample supports the opening of a separate window

To optimize the

  • Unit test coverage increased to over 85%

  • Reconstructed CLI logs and progress bars to display progress and construction results in a more friendly way

  • Document directory activation location calculation optimization

  • Batch build after file changes to improve build performance

  • Supports multi-language /zh-cn/ XXX access in URL parameters



So let’s briefly pick out a few representative features and introduce them in detail:

Customize the Home Page

Concise and good-looking home page and powerful ability to customize, so that the document has a beautiful appearance.





To configure the front page, you just need to add the Special FrontMatter hero and Features. See the custom front page on the official website for more details.

-- Title: home page order: 10 Hero: title: Docgeni Description: Out-of-the-box Angular component document generation tools Actions: -text: quick start Link: /guides/intro/getting-started btnShape: round - text: Design link: /guides/intro btnShape: square btnType: outline-primary-light features: - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature1.png title: Description: Automatically generates navigation and menus according to the directory structure, while helping developers get started with command line tools at zero cost, allowing you to quickly start documentation and component development. Title: https://cdn.pingcode.com/open-sources/docgeni/home/feature2.png for the description presents the component development: Separate Angular component preview experience, component overview, examples, apis, rich Markdown extensions, easier documentation, and support for multiple libraries at once https://cdn.pingcode.com/open-sources/docgeni/home/feature3.png title: two kinds of patterns and support a variety of style description: Supports both full and Lite modes for different needs, and supports both default and Angular styles, allowing users to choose their own theme: https://cdn.pingcode.com/open-sources/docgeni/home/feature4.png title: powerful custom description: PublicDir implements custom HTML, resources, styles, etc., while supporting fully custom site-icon: Title: https://cdn.pingcode.com/open-sources/docgeni/home/feature5.png component API automatically generated (temporarily not support) description: Automatically generate component apis based on TypeScript type definitions and annotations, maintaining consistent code and documentation - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature6.png title: multilingual support description: support flexible multi - language configurationCopy the code

Built-in component

Previously we could embed a sample component in Markdown with the
syntax, which was supposed to be the original built-in component, So this time Docgeni added three built-in components: Label, Alert and Embed.

We can do this by writing the following syntax in Markdown:

<label>Hello Docgeni</label>
<alert>Hello Docgeni</alert>
<embed src="./foo.md"></embed>
Copy the code

The Label and Alert built-in components look like this:



Embed the built-in components are embedded in a document to another document content, such as the root directory has a README, md, in a document to direct embedded README. Md all contents of the document, a copy of involved after modification need to synchronize two, For more information about built-in components: Built-in components.

Custom built-in components

In addition to the default built-in components, Docgeni also supports custom built-in components. You can use Angular to write your own built-in components and embed them in your documentation.

For example: I want to make a built-in component that sets the color of the text,

color

Create a color component in the.docgeni/ Components default folder, inherit the DocgeniBuiltInComponent base class, and export selector and Component by default. The selector here is the tag syntax in Markdown, a non-Angular component selector.

import { Component, ElementRef, HostBinding, Input, OnInit } from '@angular/core';
import { DocgeniBuiltInComponent } from '@docgeni/template';

@Component({
    selector: 'my-color',
    templateUrl: './color.component.html'
})
export class MyColorComponent extends DocgeniBuiltInComponent implements OnInit {
    @Input() set color(value: string) {
        this.hostElement.style.color = value;
    }

    constructor(elementRef: ElementRef<unknown>) {
        super(elementRef);
    }
}

export default {
    selector: 'my-color',
    component: MyColorComponent
};
Copy the code




color
 in Markdown.

The contents of a Markdown document are parsed to HTML in Docgeni using the marked library, and the content area is rendered by setting innerHTML, which means that the syntax and HTML in Markdown are not compiled by Angular. It’s directly native to the DOM, but the built-in components we write are Angular components. How do we parse and render Angular components?

  • First step: after rendering the HTML content area, by registering the built-in component of the selector to find all built-in component elements, such as label, my – color, such as all of the built-in components, contentElement. QuerySelectorAll (” label “)

  • Step 2: After finding the element, create and render the built-in component dynamically through DomPortalOutlet provided by Angular CDK, and then replace the original node

  • Step 3: Get the parameters and attributes passed in Markdown syntax, such as type and class in , Dynamically created components are passed to child components by assigning type and setting the Attribute for the Host element

The base DocgeniBuiltInComponent class provides uniform setAttribute methods so that each built-in component does not have to repeatedly provide methods to set attributes.

A series of technical difficulties were encountered:

  • Angular CDK DomPortalOutlet renders the DOM with the original node and renders the new component below the original node, resulting in multiple elements in the generated HTML, which is messy, The solution is to create a custom DomPortalOutlet that replaces appendChild with replaceWithCDK without providing custom extension capabilities for the time being

  • I originally designed a

    in the built-in component and then dynamically replaced it after rendering. It was sweet to discover that projectableNodes, the fourth parameter Angular takes to dynamically create a component, is the projection in the replacement component

    

    

    

A document catalog (TOC) supports multiple presentation forms

By default, Docgeni dynamically gets all the headings on the page, generates a tree of contents and displays them on the right side of the document. This time, toc FrontMatter configuration for the document has been added

  • Toc: Content means displayed on the right side of the document, which is the default mode

  • Toc: menu Displays in the menu on the left

  • The toc: false | hidden hidden directory

Global configuration TOC is the default directory presentation for all documents. If you want to hide all documents or display them in the left menu, set it to Menu or false.







Component support label

When we write the component library, some new or abandoned components need to be clearly marked in the menu for easy reference.









Simply write FrontMatter such as Label: New in the corresponding component document. New, Deprecated, and experimental tags are available with built-in tags, as well as custom tags and colors and copywriting that duplicate the original tags. All you need to do is set labels in the corresponding library as follows:





labels: {
"new": { "text": "New", "color": "#73D897" },
"deprecated": { "text": "Deprecated", "color": "#AAAAAA" },
"experimental": { "text": "Experimental", "color": "#F6C659" }
}
Copy the code



For details, see Library Configuration -> Labels

Friendlier progress presentation

This update also optimizes the PROGRESS and log presentation of the CLI. In order to support progress and log presentation of first and incremental builds, the underlying code has been refactored to use a Webpack-like Compilation mechanism, creating a new Compilation for each build. Logs and progress are printed and displayed through hooks events provided by the Compilation, and watchAggregated when modifying multiple files at once, building once.







This is all from Docgeni 1.1.0, welcome to Angular users, your use and feedback is the biggest support for open source.

In addition to Docgeni, we also open source several Angular related projects. You are welcome to use them:

  • The NGX-Planet Angular framework is a micro-front-end framework out of the box

  • The Angular view layer of the SLATE editor framework

  • Ngx-gantt is best used with the powerful Angular Gantt chart component,

Finally, we recommend PingCode, our intelligent R&D management tool.

PingCode website

About PingCode

PingCode is an intelligent R & D management tool created by Worktile, an established SaaS manufacturer in China. Seven sub-products, including Agile, Testhub, Wiki, Plan, Goals, Flow and Access, and application markets, have been launched to meet the needs of enterprise R&D management. The whole process of r & D management, such as project, task, requirement, defect, iteration planning, testing and objective management, has been covered, and many mainstream development tools, such as code management tools, CI/CD pipeline and automated testing, have been opened.

Since its official release, many enterprises in more than 13 industries have chosen PingCode for research and development management, represented by cooldog Music, Sensetime, Electronic Bank Information, 51 Social Security, Wanguo Data, Golden Eagle Card, Yonyou, China Auto Intelligent Control, Wisdom tooth customer service, Yiexpress and other well-known enterprises.