教程快速入门_tutorial-quickstart

以下为本文档的中文说明

tutorial-quickstart 是一个面向 TutorialKit 框架的快速入门技能，提供从项目搭建、编写第一课到部署上线的端到端指南。该技能基于 Ruby 和 Rails 技术栈，使用 TutorialKit 和 WebAssembly 技术在浏览器中运行完整的 Rails 开发环境。其核心用途是帮助教育内容创作者和技术写作者快速创建交互式的 Rails 编程教程，让学习者在浏览器中直接编写和运行 Rails 代码，无需在本地搭建开发环境。该技能的核心特点包括：一键脚手架——使用 npx create-tutorialkit-rb 命令快速创建项目，支持交互式提示和 --defaults 跳过模式，可选择 Vercel、Netlify 或 Cloudflare 作为托管服务商。交互式学习环境——教程在浏览器中运行完整的 Rails 开发环境（基于 WebAssembly），学习者可以通过嵌入式终端和代码编辑器直接实操。预设的 rails-app 模板——包含完整的用户认证系统（基于 Rails 8 的认证生成器模式）、会话登录、快速登录功能（无需密码，一键登录）、CSS 设计系统（基于 BEM 命名规范和 CSS 自定义属性）、种子数据（预置演示用户）、布局组件（导航栏、Flash 消息、容器包装器）等开箱即用的功能。完整的课程体系支持——通过目录结构组织教程内容：根目录 meta.md 定义教程元数据，part 元数据定义章节，lesson 目录包含课程内容、起始代码、参考答案代码，支持 WebContainer 运行时配置、预览端口设置和命令执行顺序控制。品牌定制——支持自定义 Logo（亮色/暗色模式）、Favicon、强调色系统、OG Meta 社交分享图、标题栏和 GitHub 链接等外观元素。部署自动化——自动处理 WebContainer 必需的 COEP/COOP HTTP 头部配置。使用场景包括技术博主创建在线的 Rails 编程课程、企业内部搭建 Ruby 技术培训平台、开源项目制作交互式入门教程，以及教育机构开展远程编程教学。该技能与 tutorial-content-structure、tutorial-lesson-config 等配套技能协同工作。

Tutorial Quickstart

End-to-end guide: scaffold a project, write your first lesson, and deploy.

Step 1: Scaffold

npx create-tutorialkit-rb my-tutorial

The CLI prompts for:

Skip all prompts with--defaults, or pass flags directly:

npx create-tutorialkit-rb my-tutorial-ppnpm--providernetlify--git

What Gets Created

my-tutorial/ ├── src/ │ ├── content/tutorial/ ← Your tutorial content goes here │ │ ├── meta.md ← Tutorial root config (already set up) │ │ └── 1-getting-started/ ← Sample part with starter lessons │ ├── templates/default/ ← WebContainer runtime (don't modify) │ └── components/ ← UI components ├── ruby-wasm/ │ └── Gemfile ← Add gems here, then rebuild WASM ├── bin/build-wasm ← Rebuilds the WASM binary ├── astro.config.ts └── package.json

Step 2: Add Your Gems

Editruby-wasm/Gemfileto include the gems your tutorial needs:

# ruby-wasm/Gemfilesource"https://rubygems.org"gem"wasmify-rails","~> 0.4.0"gem"rails","~> 8.0.0"# Your tutorial's gemsgem"action_policy"gem"devise"

Then build the WASM binary:

npmrun build:wasm# Takes up to 20 minutes on first run

Subsequent rebuilds are faster thanks to caching, but still take a few minutes.

Step 3: Start the Dev Server

npmrun dev# Starts at http://localhost:4321/

The sample tutorial loads immediately. You’ll see the starter lessons from the scaffold.

Step 4: Write Your First Lesson

4a. Create the Directory Structure

src/content/tutorial/ ├── meta.md ← Already exists (tutorial root) └── 1-basics/ ├── meta.md ← Part metadata └── 1-hello-rails/ ├── content.md ← Your lesson ├── _files/ ← Starting code │ └── workspace/ │ └── app/ │ └── controllers/ │ └── pages_controller.rb └── _solution/ ← Solution code └── workspace/ └── app/ └── controllers/ └── pages_controller.rb

4b. Write the Part Metadata

# src/content/tutorial/1-basics/meta.md---type:parttitle:The Basics---

4c. Write the Lesson

# src/content/tutorial/1-basics/1-hello-rails/content.md---type:lessontitle:Hello Railsfocus:/workspace/app/controllers/pages_controller.rbpreviews:[3000]mainCommand:['node scripts/rails.js server','Starting Rails server']prepareCommands:-['npm install','Preparing Ruby runtime']-['node scripts/rails.js db:prepare','Prepare development database']terminalBlockingPrepareCommandsCount:2custom:shell:workdir:'/workspace'---# Hello RailsOpen `app/controllers/pages_controller.rb` and add a `home` action:\\`\\`\\`ruby title="app/controllers/pages_controller.rb" ins={2-4}class PagesController < ApplicationController def homerender plain:"Hello from Rails on WebAssembly!"end end \\`\\`\\` Visit the preview to see your message.

4d. Add Starting Files

Put a skeleton file in_files/:

# _files/workspace/app/controllers/pages_controller.rbclassPagesController<ApplicationController# Add your action hereend

4e. Add

Solution Files

Put the completed code in_solution/:

# _solution/workspace/app/controllers/pages_controller.rbclassPagesController<ApplicationControllerdefhomerender plain:"Hello from Rails on WebAssembly!"endend

4f. Delete the Sample Content

Remove the scaffold’s starter lessons once you have your own:

rm-rfsrc/content/tutorial/1-getting-started/rm-rfsrc/content/tutorial/2-controllers/

Therails-appTemplate

The scaffold includes a pre-builtrails-apptemplate atsrc/templates/rails-app/with authentication, styling, and seed data ready to go. Most tutorials should extend this template rather than building from scratch.

What’s Included

• Authentication— session-based login viaAuthenticationconcern (app/controllers/concerns/authentication.rb)
• Quick login— password-free login buttons on the sign-in page for tutorial convenience
• CSS design system— modern BEM-based stylesheet with CSS custom properties
• Seed users— Alice and Bob created indb/seeds.rb
• Layout— nav bar with brand, user name, login/logout; flash messages;.containerwrapper

Authentication Flow

The template uses Rails 8’s authentication generator pattern:

• Authenticationconcern addsrequire_authenticationas abefore_action
• Controllers opt out withallow_unauthenticated_access
• Current.useris available everywhere viaCurrent.session.user
• authenticated?helper works in both controllers and views

Quick loginlets tutorial users sign in with one click instead of typing credentials:

• SessionsController#newpopulates@preauthenticate_users(all users by default)
• SessionsController#preauthenticatelogs in by user ID (no password)
• Thesessions/_preauthenticate_user.html.erbpartial renders each quick-login button
• Route:post :preauthenticate, on: :collectionunderresource :session

To customize quick-login users in a lesson, override the sessions controller in_files/:

# _files/workspace/app/controllers/sessions_controller.rbclassSessionsController<ApplicationController allow_unauthenticated_access only:%i[new create preauthenticate]defnew# Show only specific users for this lesson@preauthenticate_users=User.where(role:"agent").order(:name)end# ... rest inherited from templateend

CSS Design System

The template’sapplication.cssuses pure CSS with custom properties and BEM naming. Use these classes in your lesson ERB files — no extra setup needed.

CSS Custom Properties (:rootvariables):

BEM Components:

Customizing the Demo App for Your Domain

To turn the generic demo app into your tutorial’s domain (e.g., a Help Desk, a Store, etc.):

1. Rename the app moduleinconfig/application.rb:

moduleHelpdesk# was DemoAppclassApplication<Rails::Application

2. Add your models.Create migrations indb/migrate/and models inapp/models/. Updatedb/schema.rbto match.

3. Add controllers and views.Put CRUD controllers inapp/controllers/and ERB views inapp/views/. Use the BEM classes from the CSS design system.

4. Update routesinconfig/routes.rb.

5. Update seedsindb/seeds.rbwith domain-specific sample data. Keep the default passwords3cr3tfor all users so the quick-login flow works.

6. Update the layout— change the brand name inapp/views/layouts/application.html.erb, add nav links for your resources.

7. Update the home page— replace the hero content inapp/views/home/index.html.erb.

Step 5: Use a Template for Pre-Built State

If your lesson needs an existing Rails app (not just an empty workspace), create a template:

src/templates/my-app/ ├── .tk-config.json → { "extends": "../default" } └── workspace/ ├── app/ ├── config/ ├── db/ └── ...

Then reference it from your lesson’s_files/.tk-config.json:

{"extends":"../../../../../templates/my-app"}

See therails-file-managementskill for details on template inheritance.

Step 6: Deploy

Tutorials needCross-Origin-Embedder-PolicyandCross-Origin-Opener-Policyheaders for WebContainers to work. If you chose a hosting provider during scaffold, these are already configured.

Build for Production

npmrun build# Produces a static site in dist/

Manual Header Configuration

If you didn’t choose a provider during scaffold, add these headers to every response:

Cross-Origin-Embedder-Policy: require-corp Cross-Origin-Opener-Policy: same-origin

Vercel (vercel.json)

{"headers":[{"source":"/(.*)","headers":[{"key":"Cross-Origin-Embedder-Policy","value":"require-corp"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"}]}]}

Netlify (netlify.toml)

[[headers]] for = "/*" [headers.values] Cross-Origin-Embedder-Policy = "require-corp" Cross-Origin-Opener-Policy = "same-origin"

Cloudflare (public/_headers)

/* Cross-Origin-Embedder-Policy: require-corp Cross-Origin-Opener-Policy: same-origin

Customizing Look & Feel (Branding)

To match your tutorial’s branding to your project’s documentation site, update these files:

Logos

Replacepublic/logo.svg(light mode) andpublic/logo-dark.svg(dark mode) with your project’s logo SVG. Use a dark fill (e.g.,#0F4D8A) for the light-mode version and a light fill (e.g.,#E4E6E9) for the dark-mode version.

Title in Top Bar

Editsrc/components/TopBar.astro— add a<span>after the logo images inside the<a>tag:

<spanclass="ml-2 text-sm font-medium text-tk-elements-topBar-iconButton-iconColor whitespace-nowrap">Your Tutorial Title</span>

Favicon

Replacepublic/favicon.svgwith your project’s icon. Optionally add apublic/favicon.icofor broader browser support.

Accent Colors (UnoCSS Theme)

Override theaccentpalette inuno.config.tsto change buttons, links, active tabs, and badges site-wi
de:

import{defineConfig}from'@tutorialkit-rb/theme';exportdefaultdefineConfig({theme:{colors:{accent:{50:'#EFF6FF',100:'#E5F0FF',200:'#B6D4FF',300:'#75B5FF',400:'#4DA6FF',// dark mode accent500:'#0E7EF1',// primary interactive600:'#0F4D8A',// primary brand700:'#0C3F72',800:'#09325A',900:'#072848',950:'#041A30',},},},content:{pipeline:{include:'**'},},});

Generate your scale from your brand’s primary color. The600slot is the main brand color;500is for hover/interactive states;400is used in dark mode.

Component Hardcoded Colors

Some components use hardcoded Tailwind color classes instead of theme tokens. Search for and replace these:

• src/components/HelpDropdown.tsx— Reload button usesbg-blue-600. Change tobg-accent-600 hover:bg-accent-700.
• src/components/HeadTags.astro— Rails path link colors. Update hex values to match your brand.

Rails Demo App CSS

Update the primary color insrc/templates/rails-app/workspace/app/assets/stylesheets/application.css:

:root{--color-primary:#0F4D8A;/* your brand color */--color-primary-hover:#0C3F72;/* darker shade */--color-primary-light:#EFF6FF;/* tinted background */}

OG Meta (Social Sharing Image)

Add Open Graph meta tags so your tutorial shows a rich preview when shared on social media, Slack, etc.

1. Generate a cover image.Use a tool like myogimage.com to create a 1200×630 OG image with your tutorial title and branding.

2. Save it aspublic/cover.png.

3. Add themetakeyto your tutorial rootsrc/content/tutorial/meta.md:

---type:tutorialmeta:image:/cover.pngtitle:Your Tutorial Titledescription:|A short description of what your tutorial teaches# ... rest of frontmatter---

Themetafields map to standard OG tags (og:image,og:title,og:description) and are rendered in<head>automatically by TutorialKit.

GitHub Link

Update the repo URL insrc/components/GitHubLink.astro:

<ahref="https://github.com/your-org/your-repo"...>

Common Issues

Next Steps