YFM Docs Components

Компоненты для Yandex Flavored Markdown Documentation.

Installation

npm i @diplodoc/components

Usage

Append js

// In most cases append transform runtime
import "@doc-tools/transform/dist/js/yfm.js";

import {createRoot} from 'react-dom/client';
import {ThemeProvider} from '@gravity-ui/uikit';

// configure components
import {configure as configureUikit} from '@gravity-ui/uikit';
import {configure as configureDocs} from '@diplodoc/components';

configureUikit({lang: 'ru'});

// can be reconfigured in any moment
configureDocs({
    lang: 'ru',
    // optionally configure allowed translations
    loc: {ru, en, tr, ...}
})

// The theme must be applied. To do that wrap your app in ThemeProvider
const root = createRoot(document.getElementById('root'));
root.render(
    <ThemeProvider theme="light">
        <App />
    </ThemeProvider>,
);

Append css

/*project.css*/

/*Append components styles*/
@import '@diplodoc/components';

/*Append components theme*/
@import '@diplodoc/components/themes/common';

/*In most cases append transform styles*/
@import '@doc-tools/transform/dist/css/yfm.css';

Development

To build the project correctly you need to install python@2. Visit python.org/downloads to get the latest version.

Install Dependencies

npm ci
cd demo && npm ci

To start the development server with storybook run the following:

npm run dev

Testing

We use Playwright for testing.

Preparation

Each version of Playwright needs specific versions of browser binaries to operate.

# loads binaries
npx playwright install

By default playwright will use http://localhost:6006 as URL for storybook server.

If you want to change it, you should add .env file in repository's root directory with the data below:

# the URL where the storybook is running
BASE_URL= # for example:'http://localhost:6006'

Running tests on MacOS and Linux

All tests:

npm run playwright:docker npm run test:playwright

Single test:

npm run playwright:docker npm run test:playwright test_name.spec.ts

Several sets of test files from different folders:

npm run playwright:docker npm run test:playwright __tests__/folder1 __tests__/folder2

These commands run storybook server before tests.

If storybook server is already running, playwright will use it for tests and won't run another server.

Running tests on Windows

# add ':windows'
npm run playwright:docker:windows npm run test:playwright

Test reports

To see test reports run:

npx playwright show-report

Writing and updating tests

All tests are in ./__tests__ folder.

**.spec.ts files contain test code. To write or change tests use Playwright documentation.

For screenshot testing you need write page URL in your test file. You need page without storybook panel.

Open page without storybook panel in new tab by using 'Open canvas in new tab' button and use that URL in tests.

After running tests playwright will create folder for snapshots (if it didn't exist).

**.__screenshots__ folders contain screenshots which are used for comparison with test screenshots.

If reference screenshot is incorrect you can update it:

npm run playwright:docker npm run test:playwright --update-snapshots

License

MIT