以下为本文档的中文说明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 QuickstartEnd-to-end guide: scaffold a project, write your first lesson, and deploy.Step 1: Scaffoldnpx create-tutorialkit-rb my-tutorialThe CLI prompts for:PromptDefaultNotesTutorial namerandom (e.g., “fierce-turtle”)Used aspackage.jsonnameDirectory./{name}Where files are createdHosting providerSkipVercel, Netlify, or Cloudflare — adds COEP/COOP headersPackage managernpmnpm, yarn, pnpm, or bunInit git repo?YesCreates initial commitEdit Gemfile?YesOpensruby-wasm/Gemfilein$EDITORSkip all prompts with--defaults, or pass flags directly:npx create-tutorialkit-rb my-tutorial-ppnpm--providernetlify--gitWhat Gets Createdmy-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 (dont modify) │ └── components/ ← UI components ├── ruby-wasm/ │ └── Gemfile ← Add gems here, then rebuild WASM ├── bin/build-wasm ← Rebuilds the WASM binary ├── astro.config.ts └── package.jsonStep 2: Add Your GemsEditruby-wasm/Gemfileto include the gems your tutorial needs:# ruby-wasm/Gemfilesourcehttps://rubygems.orggemwasmify-rails,~ 0.4.0gemrails,~ 8.0.0# Your tutorials gemsgemaction_policygemdeviseThen build the WASM binary:npmrun build:wasm# Takes up to 20 minutes on first runSubsequent rebuilds are faster thanks to caching, but still take a few minutes.Step 3: Start the Dev Servernpmrun 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 Lesson4a. Create the Directory Structuresrc/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.rb4b. 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 titleapp/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 FilesPut a skeleton file in_files/:# _files/workspace/app/controllers/pages_controller.rbclassPagesControllerApplicationController# Add your action hereend4e. AddSolution FilesPut the completed code in_solution/:# _solution/workspace/app/controllers/pages_controller.rbclassPagesControllerApplicationControllerdefhomerender plain:Hello from Rails on WebAssembly!endend4f. Delete the Sample ContentRemove the scaffold’s starter lessons once you have your own:rm-rfsrc/content/tutorial/1-getting-started/rm-rfsrc/content/tutorial/2-controllers/Therails-appTemplateThe 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 IncludedAuthentication— session-based login viaAuthenticationconcern (app/controllers/concerns/authentication.rb)Quick login— password-free login buttons on the sign-in page for tutorial convenienceCSS design system— modern BEM-based stylesheet with CSS custom propertiesSeed users— Alice and Bob created indb/seeds.rbLayout— nav bar with brand, user name, login/logout; flash messages;.containerwrapperAuthentication FlowThe template uses Rails 8’s authentication generator pattern:Authenticationconcern addsrequire_authenticationas abefore_actionControllers opt out withallow_unauthenticated_accessCurrent.useris available everywhere viaCurrent.session.userauthenticated?helper works in both controllers and viewsQuick loginlets tutorial users sign in with one click instead of typing credentials:SessionsController#newpopulatespreauthenticate_users(all users by default)SessionsController#preauthenticatelogs in by user ID (no password)Thesessions/_preauthenticate_user.html.erbpartial renders each quick-login buttonRoute:post :preauthenticate, on: :collectionunderresource :sessionTo customize quick-login users in a lesson, override the sessions controller in_files/:# _files/workspace/app/controllers/sessions_controller.rbclassSessionsControllerApplicationController allow_unauthenticated_access only:%i[new create preauthenticate]defnew# Show only specific users for this lessonpreauthenticate_usersUser.where(role:agent).order(:name)end# ... rest inherited from templateendCSS Design SystemThe 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):CategoryVariablesExampleColors--color-primary,--color-danger,--color-success,--color-warning,--color-infocolor: var(--color-primary)Text--color-text,--color-text-muted,--color-text-inversecolor: var(--color-text-muted)Background--color-bg,--color-bg-white,--color-borderbackground: var(--color-bg)Spacing--space-xsthrough--space-2xlpadding: var(--space-md)Typography--font-sans,--font-mono,--font-size-smthrough--font-size-3xlfont-size: var(--font-size-lg)Radius--radius-smthrough--radius-xlborder-radius: var(--radius-md)Shadows--shadow-sm,--shadow-mdbox-shadow: var(--shadow-sm)BEM Components:ComponentClassesUsageButton.btn,.btn--primary,.btn--danger,.btn--small,.btn--linkLinks, submits, actionsInput.input,.input--errorText fields, selects, textareasCard.card,.card__header,.card__body,.card__footerContent containersAlert.alert,.alert--error,.alert--success,.alert--info,.alert--warningFlash messages, noticesBadge.badge,.badge--primary,.badge--success,.badge--danger,.badge--warningStatus labels, role tagsNav.nav,.nav__brand,.nav__link,.nav__userTop navigation (in layout)Form.form__group,.form__label,.form__hint,.form__errors,.form__actionsForm layoutTable.tableData tables with hover rowsPage header.page-headerTitle action button rowHero.hero,.hero__title,.hero__subtitle,.hero__actionsLanding/home pagesQuick login.quick-login,.quick-login__btn,.quick-login__name,.quick-login__emailSign-in pageUtility.text-muted,.text-sm,.mt-md,.mb-md,.inline-actions,.containerSpacing, text helpersCustomizing the Demo App for Your DomainTo 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 DemoAppclassApplicationRails::Application2. 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 StateIf 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: DeployTutorials 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 Productionnpmrun build# Produces a static site in dist/Manual Header ConfigurationIf 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-originVercel (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-originCloudflare (public/_headers)/* Cross-Origin-Embedder-Policy: require-corp Cross-Origin-Opener-Policy: same-originCustomizing Look Feel (Branding)To match your tutorial’s branding to your project’s documentation site, update these files:LogosReplacepublic/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 BarEditsrc/components/TopBar.astro— add aspanafter the logo images inside theatag:spanclassml-2 text-sm font-medium text-tk-elements-topBar-iconButton-iconColor whitespace-nowrapYour Tutorial Title/spanFaviconReplacepublic/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-wide:import{defineConfig}fromtutorialkit-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 ColorsSome 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 CSSUpdate 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 inheadautomatically by TutorialKit.GitHub LinkUpdate the repo URL insrc/components/GitHubLink.astro:ahrefhttps://github.com/your-org/your-repo...Common IssuesProblemCauseFixbuild:wasmfailsMissing WASI SDK or build toolsCheckrbwasmprerequisitesPreview shows nothingServer not startedAddmainCommand: [node scripts/rails.js server, ...]Terminal stuck on “Preparing”WASM binary not builtRunnpm run build:wasmfirstFiles not appearing in editorWrong pathAll Rails files must be underworkspace/app/Database emptyNodb:preparein prepareCommandsAdd[node scripts/rails.js db:prepare, ...]Deploy fails with blank pageMissing COEP/COOP headersAdd headers per provider instructions aboveNext StepsWant to…See skillStructure parts, chapters, lessonstutorial-content-structureConfigure frontmatter optionstutorial-lesson-configOrganize Rails files properlyrails-file-managementCheck if a feature works in WASMrails-wasm-author-constraintsGet a recipe for a specific lesson typerails-lesson-recipes48:T5d0,Use this skill whenever starting a new tutorial project, understanding the end-to-endworkflow from scaffold to deployment, or working with the rails-app template’s built-infeatures. Trigger when the user says ‘new tutorial’, ‘create tutorial’, ‘getting started’,‘npx create-tutorialkit-rb’, ‘scaffold’, ‘first lesson’, ‘deploy tutorial’, ‘build:wasm’,‘COEP headers’, ‘COOP headers’, ‘hosting setup’, ‘CSS classes’, ‘BEM components’,‘design system’, ‘application.css’, ‘quick login’, ‘preauthenticate’, authenticationsetup’, ‘customize demo app’, ‘seed users’, ‘rails-app template’, ‘branding’, ‘logo’,‘favicon’, ‘accent color’, ‘theme color’, ‘look and feel’, ‘customize colors’,‘OG image’, ‘og:image’, ‘cover image’,‘social preview’, ‘meta tags’, ‘og meta’, or askshow to set up, build, style, brand, or deploy a Rails tutorial from scratch — even ifthey don’t explicitly mention quickstart. This skill provides the exact CLI commands,project structure, WASM build steps, rails-app template features (CSS design system,authentication, quick login), branding customization (logos, favicons, accent colors,top bar title, component colors, OG meta for social sharing), demo app customizationsteps, deployment header configuration, and common issue troubleshooting. Do NOT attempt project setup or deployment without this skill. Do NOTuse for detailed frontmatter reference (use tutorial-lesson-config) or WASM compatibilityquestions (use rails-wasm-author-constraints).