Docgeni 1.1.0 officially released!

Time:2021-10-18

This article is shared by the person in charge of worktile product R & D department @ Xu Haifeng

On May 20, 2021, docgeni officially announced open source. See the detailsDocgeni, an out of the box angular component documentation tool, after more than four months, docgeni is also growing slowly. In order to celebrate the national day, it is finally here today1.1.0For the release of version, let’s introduce it in detail1.1.0What are the new features.

If you haven’t followed docgeni, you can gohttps://github.com/docgeni/do…Star, wait a minute.
Official website address:https://docgeni.org

1.1.0 update count
New features

  • fullCustom home page function in mode
  • customfooterfunction
  • Document directory (TOC) supports multiple presentation forms(content | menu | hidden
  • The component supports label display, which is included by defaultnewdeprecatedandexperimental
  • newly addedlabelalertandembedBuilt in component, embedded through markdown extension syntax
  • Support custom built-in components and embed them through markdown extension syntax
  • The contributors and last update time of GitHub are displayed at the bottom of the document
  • The last and next articles are displayed at the bottom of the document
  • The component example supports independent window opening

optimization

  • Unit test coverage increased to more than 85%
  • Refactor cli logs and progress bars to show progress and build results in a more friendly way
  • Document directory activation location calculation optimization
  • Batch build after file changes to improve build performance
  • Support access to multiple languages in URL parameters/zh-cn/xxx

Then, let’s briefly select several representative features and introduce them in detail:

Custom home page
Simple and good-looking home page and strong customization ability make the document have a beautiful appearance.
Docgeni 1.1.0 officially released!
Configuring the home page is the same as writing ordinary documents. You only need to addheroandfeaturesspecialFrontMatterYou can view the details on the official websiteCustom home pageLearn more.

---
Title: home page
order: 10
hero:
  title: Docgeni
  Description: out of the box angular component document generation tool
  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: out of the box
    Description: automatically generate navigation and menus according to the directory structure, and help developers get started at zero cost through command-line tools, so that you can quickly start document writing and component development
  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature2.png
    Title: born for angular component development
    Description: independent angular component preview experience, component overview, examples, APIs and rich markdown extensions make it easier to write documents and support the existence of multiple class libraries at the same time 
  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature3.png
    Title: two modes and multiple styles support
    Description: full and Lite modes are supported to meet different needs. At the same time, default and angular styles are supported to allow users to choose their own theme
  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature4.png
    Title: powerful customization capability
    Description: publicdir is provided to realize functions such as custom HTML, resources, styles, etc. at the same time, it supports fully customized sites
  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature5.png
    Title: automatic generation of component API (not supported temporarily)
    Description: automatically generate component API based on typescript type definition and comments, and maintain the consistency of code and documents
  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature6.png
    Title: Multilingual Support
    Description: support flexible multilingual configuration
---

Built in components
Before, we could pass in markdown <example name="xxx" inline />A sample component is embedded in the syntax. In fact, this should be the original built-in component, so docgeni adds this time label alertandembedThree built-in components.
We can write the following syntax in markdown:

<label>Hello Docgeni</label>
<alert>Hello Docgeni</alert>
<embed></embed>

The display effects of the built-in components of label and alert are as follows:
Docgeni 1.1.0 officially released!

The embedded built-in component is to embed the contents of another document in one document. For example, there is already one in the root directoryREADME.md, you want to embed it directly in the documentREADME.mdIf you need to synchronize two copies of all the contents of a document when copying one involves subsequent modifications, you can use it directly<embed></embed>It is the best scheme. At the same time, you can specify to embed a certain row and row interval content. For more use of built-in components:Built in components

Custom built-in components
In addition to providing default built-in components, docgeni also supports custom built-in components this time. You can use angular to write the built-in components you want, and then embed them in the document.
For example, I want to develop a built-in component for setting text color,<my-color color="red">Color</my-color>
Then you just need to.docgeni/componentsCreate a new color component in the default folder and inherit itDocgeniBuiltInComponentBase class. You can export the selector and component by default. The selector here is the tag syntax in markdown, not the selector of angular components.

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
};

This allows you to write in markdown<my-color color="red">Color</my-color> Achieve the effect of setting text color.

In docgeni, the markdown document content is parsed into HTML through the marked library, and then the content area is setinnerHTMLRendered, which means that the syntax and HTML in markdown will not be compiled by angular, but it is directly a native dom. However, the built-in component we write is an angular component, so how to parse and render the angular component?

  • Step 1: after rendering HTML in the content area, use the registered built-in componentsselector Find all built-in component elements, such aslabelmy-colorAnd all built-in components,contentElement.querySelectorAll("label")
  • Step 2: after finding the element, use the provided by angular CDKDomPortalOutlet​Dynamically create and render built-in components, and then replace the original nodes
  • Step 3: get the parameters and attributes passed in markdown syntax, such as type and class in < label type = “primary” class = “label” > < / label >, and transfer them to the sub components by assigning type and setting the attribute of the host element after dynamically creating the component

In order to prevent each built-in component from repeatedly providing methods for setting properties, the base class docgenibuiltincomponent , provides a unified methodsetAttribute​method.

There are several technical difficulties:
Angular CDK DomPortalOutlet​Rendering DOM will retain the original nodes and render new components below the original nodes, resulting in multiple elements in the generated HTML, which are untidy. The solution is to customize oneDomPortalOutlet​holdappendChild InsteadreplaceWith​CDKThe user-defined extension capability is not provided temporarily
According to the syntax written in markdown, how to project the content into the angular built-in component. At first, my design was to write one in the built-in component<div id="dg-content"></div>​Then it is dynamically replaced after rendering. Later, it is found that angular is dynamically creating the fourth parameter of the component projectableNodes​It is to replace the < ng content > projection in the component, which suddenly feels so fragrant
Docgeni 1.1.0 officially released!

Document directory (TOC) supports multiple presentation forms
By default, docgeni will dynamically get all the headers of the page, generate a tree directory and display it on the right side of the document. This time, the TOC frontmatter of the document is added to configure multiple display forms

* toc: content​It is displayed on the right side of the document, which is the default mode

  • toc: menu​It is displayed in the menu on the left
  • toc: false | hidden​Indicates a hidden directory

meanwhileGlobal configuration TOCIs to configure the default directory presentation of all documents. If you want to hide all documents or display them in the left menu, you can configure it asmenu​perhapsfalse​
Docgeni 1.1.0 officially released!

Component support label
When we write the component library, some new or abandoned components need to be clearly identified in the menu for easy reference.
Docgeni 1.1.0 officially released!
You only need to write it in the corresponding component documentlabel: new​ Such frontmatter is sufficient. This timenew​deprecatedandexperimental​Three built-in tags are also providedCustomize the color and copy of the label and overwrite the original label。 You only need to configure labels in the corresponding class library. The configuration is as follows:

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

Detailed description reference:Class library configuration – > labels

More friendly progress display
This update also optimizesCLI progress and log presentation, in order to support the progress and log display of the first and incremental build, the underlying code is refactored, using a method similar to webpackCompilation​Mechanism to create a new one at a timeCompilation​At the same time, the log and progress are throughCompilation​The hooks event is printed and displayed, and the underlying layer also provides watchAggregated​Method. When multiple files are modified at one time, they will be sent in batches and built only once.
Docgeni 1.1.0 officially released!

The above is Docgeni 1.1.0​ All the contents released by the version are welcome to be concerned and used by angular users. Your use and feedback are the greatest support for open source.
In addition to docgeni, we also open source several angular related projects. Welcome to use:

* ngx-planet Angular Micro front-end frame out of the box

Finally, we recommend our intelligent R & D management tool pingcode to you.

Pingcode official website

About pingcode

Pingcode is an intelligent R & D management tool created by worktile, an old SaaS manufacturer in China. Around the needs of enterprise R & D management, it has launched seven sub products and application markets: agile (Agile Development), testhub (test management), Wiki (knowledge base), plan (project set), goals (objective management), flow (automatic management) and access (directory management), It covers the whole process of R & D management such as project, task, requirements, defects, iterative planning, testing and target management, and opens up many mainstream development tools such as code hosting tools, CI / CD pipeline and automatic testing.

Since its official release, many enterprises in more than 13 industries have chosen pingcode for R & D management, represented by well-known enterprises such as kugou music, Shangtang technology, e-banking information, 51 social security, Wanguo data, Golden Eagle cartoon, UFIDA, Guoqi intelligent control, wisdom tooth customer service and easy express.