h5p-type-scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

H5P Content Type Scaffolder

H5P内容类型脚手架工具

Create a modern H5P content type starting from established boilerplates, with a minimal build pipeline and editor semantics.

创建基于成熟模板的现代化H5P内容类型，配备轻量构建流水线和编辑器语义规范。

How It Works

工作流程

Collect metadata (title, machine name, version, author, license).
Generate a boilerplate (default: SNORDIAN) that aligns with current H5P best practices.
Provide starter
```
library.json
```
,
```
semantics.json
```
, and JS/CSS entrypoints.
Outline build and packaging steps using
```
h5p-cli
```
.

收集元数据（标题、机器名称、版本、作者、许可证）。
生成符合当前H5P最佳实践的模板（默认：SNORDIAN）。
提供初始的
```
library.json
```
、
```
semantics.json
```
以及JS/CSS入口文件。
介绍使用
```
h5p-cli
```
进行构建和打包的步骤。

Concepts

核心概念

Content types are runnable libraries under
```
H5P.*
```
(
```
runnable: 1
```
).
Editor widgets are non-runnable libraries under
```
H5PEditor.*
```
(
```
runnable: 0
```
).
```
semantics.json
```
defines the editor form schema and validation rules.
Non-runnable dependency libraries (often
```
H5P.*
```
or
```
H5PApi.*
```
) are used as shared building blocks.

See

references/CONCEPTS.md

for details and official links.

内容类型是
```
H5P.*
```
下的可运行库（
```
runnable: 1
```
）。
编辑器组件是
```
H5PEditor.*
```
下的非运行库（
```
runnable: 0
```
）。
```
semantics.json
```
定义编辑器表单的 schema 和验证规则。
非运行依赖库（通常为
```
H5P.*
```
或
```
H5PApi.*
```
）作为共享构建模块使用。

详情及官方链接请查看

references/CONCEPTS.md

。

Usage

使用方法

bash

bash /mnt/skills/user/h5p-type-scaffold/scripts/scaffold.sh \
  --title "My Content Type" \
  --machine "H5P.MyContentType" \
  --kind "content" \
  --version "1.0.0" \
  --description "Short description" \
  --author "Your Name" \
  --license "MIT" \
  --template "snordian" \
  --out /path/to/output

Editor widget example:

bash

bash /mnt/skills/user/h5p-type-scaffold/scripts/scaffold.sh \
  --title "My Editor Widget" \
  --machine "H5PEditor.MyWidget" \
  --kind "editor" \
  --out /path/to/output

bash

bash /mnt/skills/user/h5p-type-scaffold/scripts/scaffold.sh \
  --title "My Content Type" \
  --machine "H5P.MyContentType" \
  --kind "content" \
  --version "1.0.0" \
  --description "Short description" \
  --author "Your Name" \
  --license "MIT" \
  --template "snordian" \
  --out /path/to/output

编辑器组件示例：

bash

bash /mnt/skills/user/h5p-type-scaffold/scripts/scaffold.sh \
  --title "My Editor Widget" \
  --machine "H5PEditor.MyWidget" \
  --kind "editor" \
  --out /path/to/output

Output

输出内容

```
library.json
```
and
```
semantics.json
```
```
src/entries
```
,
```
src/scripts
```
,
```
src/styles
```
```
README.md
```
(templates)
```
DEV.md
```
(templates, dev harness)
Build config and lint config (varies by template)
Templates live under
```
assets/templates/
```

```
library.json
```
和
```
semantics.json
```
文件
```
src/entries
```
,
```
src/scripts
```
,
```
src/styles
```
目录
```
README.md
```
（模板文件）
```
DEV.md
```
（模板文件，开发工具说明）
构建配置和代码检查配置（根据模板不同有所差异）
模板文件存放于
```
assets/templates/
```
目录下

Build & Package (h5p-cli)

构建与打包（h5p-cli）

Install deps:
```
npm install
```
Build assets:
```
npm run build
```
Set up dev environment:
```
h5p core
```
then
```
h5p setup <library>
```
Run local editor/server:
```
h5p server
```

Pack to

.h5p

h5p pack <library> [my.h5p]

(see

h5p help pack

)

安装依赖：
```
npm install
```
构建资源：
```
npm run build
```
搭建开发环境：先执行
```
h5p core
```
，再执行
```
h5p setup <library>
```
启动本地编辑器/服务器：
```
h5p server
```

打包为

.h5p

文件：

h5p pack <library> [my.h5p]

（查看

h5p help pack

获取详情）

Dev Harness (h5p-cli)

开发工具集（h5p-cli）

Manual steps:
```
references/DEV-HARNESS.md
```
Helper script:
```
scripts/h5p-dev.sh
```

手动步骤：
```
references/DEV-HARNESS.md
```
辅助脚本：
```
scripts/h5p-dev.sh
```

xAPI Integration

xAPI 集成

Guidance:
```
references/XAPI.md
```
(emit + listen + platform notes)

See

references/H5P-CLI.md

for a fuller command overview and

references/CONTENT-TYPE-AUTHORING.md

for authoring essentials.

指导文档：
```
references/XAPI.md
```
（事件触发、监听及平台相关说明）

完整命令概览请查看

references/H5P-CLI.md

，内容类型创作基础请查看

references/CONTENT-TYPE-AUTHORING.md

。

Guidance (2024/2025 Best Practices)

指导建议（2024/2025 最佳实践）

Default to the SNORDIAN boilerplate for linting, i18n scaffolding, and CI-ready conventions.
Use the official
```
h5p/h5p-boilerplate
```
when you want the simplest baseline.
Prefer vanilla JS for community maintainability.
Use
```
h5p-cli
```
to pack and manage libraries.
Validate semantics and editor UX early with a minimal field set.

默认使用SNORDIAN模板，它包含代码检查、国际化脚手架及CI就绪规范。
若需要最简基础模板，使用官方的
```
h5p/h5p-boilerplate
```
。
优先使用原生JS以提升社区可维护性。
使用
```
h5p-cli
```
进行打包和库管理。
尽早用最小字段集验证语义规范和编辑器用户体验。

Related Community Patterns (Incorporated)

已整合的社区通用模式

H5P content is often embedded via iframe in LMS or CMS platforms.
Common education-focused content types include Interactive Video, Course Presentation, Question Sets, Dialog Cards, and Timeline.
When embedding, wrap iframes in a responsive container and apply safe, minimal styling.

H5P内容通常通过iframe嵌入到LMS或CMS平台中。
常见的教育类内容类型包括交互式视频、课程演示、试题集、对话卡片和时间线。
嵌入时，需将iframe包裹在响应式容器中，并应用安全、简约的样式。

Templates

模板类型

```
snordian
```
(default): Linting + i18n scaffolding + modern webpack config.
```
vanilla
```
: Official minimal boilerplate structure.
```
editor
```
: H5P editor widget boilerplate (
```
H5PEditor.*
```
).

```
snordian
```
（默认）：包含代码检查、国际化脚手架、现代化webpack配置。
```
vanilla
```
：官方最简模板结构。
```
editor
```
：H5P编辑器组件模板（
```
H5PEditor.*
```
）。

Additional Upstream Options (Not Bundled)

其他可选上游模板（未捆绑）

h5p/h5p-boilerplate

branches like

question-type

and

question-type-vue

for specialized starting points.

```
otacke/h5p-editor-boilerplate
```
for building custom H5P editor widgets.
```
NDLA-H5P/generator-h5p-content-type
```
if you prefer a Yeoman-based generator workflow.
```
tarmoj/h5p-react-boilerplate
```
for a React-based starter (note: appears stale).

```
h5p/h5p-boilerplate
```
的
```
question-type
```
和
```
question-type-vue
```
分支，适用于特定场景的初始模板。
```
otacke/h5p-editor-boilerplate
```
：用于构建自定义H5P编辑器组件。
```
NDLA-H5P/generator-h5p-content-type
```
：若偏好基于Yeoman的生成器工作流可选用。
```
tarmoj/h5p-react-boilerplate
```
：基于React的初始模板（注意：该项目已停止维护）。

Troubleshooting

问题排查

If machine name is invalid, use
```
H5P.YourContentType
```
.
For editor widgets, use
```
--kind editor
```
and a
```
H5PEditor.YourWidget
```
machine name.
If versioning is unclear, start with
```
1.0.0
```
and update later.
If build fails, ensure
```
node
```
and
```
npm
```
are installed and run
```
npm install
```
.

若机器名称无效，请使用
```
H5P.YourContentType
```
格式。
开发编辑器组件时，需使用
```
--kind editor
```
参数，并采用
```
H5PEditor.YourWidget
```
格式的机器名称。
若版本号不确定，可从
```
1.0.0
```
开始，后续再更新。
若构建失败，请确保已安装
```
node
```
和
```
npm
```
，并执行
```
npm install
```
安装依赖。