FAQ - dumi

What is the relationship between dumi and Umi?

The dumi actually is a preset of Umi —— @umijs/preset-dumi, which means that we can use dumi in a Umi project at the same time. However, in order to avoid conflicts between the configurations of the Umi project and the dumi document, it is recommended to use UMI_ENV to distinguish.

Are these all configurations? What if I need more features?

dumi is based on Umi, Which means in addition to the configurations provided by itself, it also supports all configurations of Umi, and also supports the plugins of Umi, so if you need more features, you can first check whether Umi's configurations and plugins can be satisfied. If still cannot be satisfied, welcome to feedback to the discuss group or give a Feature Request on GitHub

Why `README.md` appears on the homepage of the document?

Whether it is a document or an website, there must be a home page. Dumi will first look for index.md or README.md as the homepage in all resolve.includes folders, if not found, it will use README.md in the project root directory as the homepage.

How to fully customize the homepage?

At present, dumi has not yet support the theme customization function, but it can be realized by importing the external embedded Demo:

<!-- index.md -->

<code src="path/to/homepage.tsx" inline />

For detailed usage, please refer to use in dumi of Ant Design Landing

How to customize "Edit this page"?

When you set the repository in the package.json of the root directory, dumi will generate the corresponding edit doc button at the bottom of the page. E.g:

// package.json
{
  "repository": {
    "type": "git",
    "url": "git+https://github.com/umijs/dumi.git",
    "branch": "master",
    "platform": "github"
  }
}

Among:

url: Decide to jump to the repository path
branch: Corresponding to the repository branch. Default is master
platform: Corresponding platform. When the current setting is gitlab, if the url involves subgroups, it will be treated specially

Does dumi support to write documents in other ways rather than `.md`?

Sorry, it is not supported yet

How to use dumi in non-Umi projects such as cra?

Source code

Install the dependence.

yarn add dumi cross-env -D

Add a start-up command in package.json

"scripts": {
    "dumi": "cross-env APP_ROOT=dumi dumi dev",
    "dumi-build": "cross-env APP_ROOT=dumi dumi build"
  },

Create dumi/config/config.js, and add configuration

export default {
  chainWebpack(memo) {
    memo.plugins.delete('copy');
  },
};

Create a new document directory dumi/docs/, where the dumi directory is the environment variable configured in the second step, you can modify it at will.
Create dumi/docs/index.md.

# This is a demo of dumi combined with create-react-app

Add the temporary files of dumi into .gitignore.

.umi

Does dumi support to write documents and demos based on other frameworks, such as Vue and Angular?

Sorry, it's not supported yet. But Umi 3 has abstracted the renderer from the structure. If there are other renderers in the future, dumi will also follow up.

How to add statistical scripts and global CSS styles?

You can configurate it through styles and scripts of Umi.

Local development is works, but will get a 404 after deployment and visiting

There is only one index.html is output as the entry HTML file by default. The server can find the file while path is / but /some-route does not have a corresponding /some-route/index.html, so it will get a 404. You can set config.exportStatic to {} which is means output all HTML files in a folder structure according to the route. For more usage of this configuration, please refer to the Umi document: Config - exportStatic.

The bundle after document building is too large, which brings about slow website access. How to implement load-on-demand mode?

You can set config.dynamicImport to {}. For more usage fo this configuration, please refer to the Umi document: Config - dynamicImport.

Deploy documents

Deploy to a non-root directory of domain

Configurating base and publicPath (depends on the actual situation) of Umi will works

export default {
  base: '/docs-base-route-path',
  publicPath: '/assets-files-base-path/',
  exportStatic: {}, // Export all routes as HTML directory structure to avoid 404 when refreshing the page
  // Other configuration
};

If the document project were independent, you would configure base and publicPath as same!

Deploy on Github Pages

Since GitHub Pages is deployed in a non-domain name root path, the base and publicPath configurations are set to the repository name before deployment. See Deploy to a non-root directory of domain

Manual deployment

With the help of gh-pages, you can easily deploy documents to Github Page

npm install gh-pages --save-dev

yarn add gh-pages -D

Add in package.json

"scripts": {
  "deploy": "gh-pages -d dist"
}

Compile to dist directory

npm run docs:build

One-click release

npm run deploy

Automatic deployment

With the help of Github Action, projects will automatically deployed after each update of master branch

Create .github/workflows/gh-pages.yml

name: github pages

on:
  push:
    branches:
      - master # default branch

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
      - run: npm install
      - run: npm run docs:build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs-dist

During the development, how to configure the styles in the md file in load-on-demand?

Dumi will alias pkgName/es, pkgName/lib, for details, see

Configure extraBabelPlugins (Attention, it is a configuration of .umirc.ts, not .fatherrc.ts), add babel-plugin-import, and configure reasonably according to the directory structure.

For example：

Here is the directory structure：

├── scripts
│   └── hack-depend.js
├── src
│   ├── Button
│   │   ├── style
│   │   │   ├── index.less
│   │   │   └── mixin.less
│   │   ├── index.md
│   │   └── index.tsx
│   ├── style
│   │   ├── base.less
│   │   ├── color.less
│   │   └── mixin.less
│   └── index.ts
├── .editorconfig
├── .fatherrc.ts
├── .gitignore
├── .prettierignore
├── .prettierrc
├── .umirc.ts
├── README.md
├── package.json
├── tsconfig.json
├── typings.d.ts
└── yarn.lock

In .umirc.ts：

extraBabelPlugins: [
  [
    'import',
    {
      libraryName: 'lean',
      camel2DashComponentName: false,
      customStyleName: name => {
        return `./style/index.less`; // Attention: the ./ cannot be omitted in here
      },
    },
    'lean',
  ],
];

Import component in md:

import { Button } from 'lean'; // load-on-demand styles here

How does dumi support to highlight for languages such as Swift, C#, Kotlin?

The prism-react-renderer used for highlighting in dumi, is a React component based on PrismJS. PrismJS supports many languages, but prism-react-renderer has removed some languages when implemented. For more specific reasons, please refer to Adding Out of the Box Languages

We can add support for other languages in dumi in the following ways:

// src/app.ts
import Prism from 'prism-react-renderer/prism';

(typeof global !== 'undefined' ? global : window).Prism = Prism;

require('prismjs/components/prism-kotlin');
require('prismjs/components/prism-csharp');

Use dumi in non-Umi project then got Error: register failed, invalid key xx from plugin src/app.ts

Because of src/app.(t|j)sx? is dumi's runtime configuration module, please avoid use this path, you can also use the [APP_ROOT way](#How to use dumi in non-Umi projects such as cra?) to workaround this if your project must use this path.

dumi