diff --git a/docs/src/docPages/guide/accessibility.md b/docs/src/docPages/guide/accessibility.md new file mode 100644 index 000000000..8e5a68b9f --- /dev/null +++ b/docs/src/docPages/guide/accessibility.md @@ -0,0 +1,26 @@ +# Accessibility + +## toc + +## Introduction +We strive to make tiptap accessible to everyone, but to be honest, there’s not much work done now. From our current understanding, that’s what needs to be done: + +### Interface +An interface needs to have semantic markup, must be keyboard accessible and well documented. Currently, we don’t even provide an interface, so for now that’s totally up to you. But no worries, we’ll provide an interface soon and take accessibility into account early on. + +### Editor +The editor needs to produce semantic markup, must be keyboard accessible and well documented. The tiptap content is well structured so that’s a good foundation already. That said, we can add support and encourage the usage of additional attributes, for example the Alt-attribute for images. + +### Writing assistance (optional) +An optional writing assitance could help people writing content semanticly correct, for example pointing out an incorrect usage of heading levels. With that kind of assistance provided by the core developers, we could help to improve the content of a lot of applications. + +## Resources + +| Document | Section | Heading | +| -------- | ------- | -------------------------------------------------------------------------------------- | +| WCAG 2.1 | 1.1 | [Text Alternatives](https://www.w3.org/WAI/WCAG21/Understanding/text-alternatives) | +| WCAG 2.1 | 1.1.1 | [Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content) | +| WCAG 2.1 | 2.1 | [Keyboard Accessible](https://www.w3.org/WAI/WCAG21/Understanding/keyboard-accessible) | +| WCAG 2.1 | 2.1.1 | [Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) | +| WCAG 2.1 | 4.1.1 | [Parsing](https://www.w3.org/WAI/WCAG21/Understanding/parsing) | +| WCAG 2.1 | 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) | diff --git a/docs/src/docPages/guide/typescript.md b/docs/src/docPages/guide/typescript.md new file mode 100644 index 000000000..0e4a1a01f --- /dev/null +++ b/docs/src/docPages/guide/typescript.md @@ -0,0 +1,51 @@ +# Working with TypeScript + +## toc + +## Introduction +The whole tiptap is code base is written in TypeScript. If you haven’t heard of it or never used it, no worries. You don’t have to. + +TypeScript extends JavaScript by adding types (hence the name). It adds new syntax, which doesn’t exist in plain JavaScript. It’s actually removed before running in the browser, but this step – the compilation – is important to find bugs early. It checks if you passe the right types of data to functions. For a big and complex project, that’s very valuable. It means we’ll get notified of lot of bugs, before shipping code to you. + +Anyway, if you don’t use TypeScript in your project, that’s fine. You’ll still be able to use tiptap and even get a really nice autocomplete for the tiptap API (if your editor supports it, but most do). + +If you’re using TypeScript in your project and want to extend tiptap, there are two things that are good to know. + +## Options type +To extend or create default options for an extension, you’ll need to define a custom type, here is an example: + +```ts +import { Extension } from '@tiptap/core' + +export interface CustomExtensionOptions { + awesomeness: number, +} + +const CustomExtension = Extension.create({ + defaultOptions: { + awesomeness: 100, + }, +}) +``` + +## Command type +The core package also exports a `Command` type, which needs to be added to all commands that you specify in your code. Here is an example: + +```ts +import { Command, Extension } from '@tiptap/core' + +const CustomExtension = Extension.create({ + addCommands() { + return { + /** + * Comments will be added to the autocomplete. + */ + yourCommand: (): Command => ({ commands }) => { + // … + }, + } + }, +}) +``` + +That’s basically it. We’re doing all the rest automatically. diff --git a/docs/src/links.yaml b/docs/src/links.yaml index d03fc02f6..6fbf3c013 100644 --- a/docs/src/links.yaml +++ b/docs/src/links.yaml @@ -72,11 +72,14 @@ - title: Complex node views link: /guide/node-views type: draft - - title: Working with TypeScript - link: /guide/working-with-typescript - title: Collaborative editing link: /guide/collaborative-editing type: pro + - title: Accessibility + link: /guide/accessibility + type: draft + - title: Working with TypeScript + link: /guide/typescript - title: API items: