Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(astro): support lessons without parts or chapters #374

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

AriPerkkio
Copy link
Member

@AriPerkkio AriPerkkio commented Oct 14, 2024

Adds support for defining lessons without chapters or parts.

src/content/tutorial
│
├── meta.md # Tutorial metadata
│
└── lesson-1 # Lesson in root! No part or chapter.
   ├── content.md
   ├── _files
   └── _solution
src/content/tutorial
│
├── meta.md # Tutorial metadata
│
└── part-1
    └── lesson-1 # Lesson in part! No chapter.
        ├── content.md
        ├── _files
        └── _solution

Custom order can be defined using lessons in metadata:

---
type: 'tutorial'
lessons: ['lesson-one', 'lesson-two']
---
---
type: 'part'
lessons: ['lesson-one', 'lesson-two']
---

Mixing structures is not supported and an error is thrown when these are not followed:

  • A tutorial can have one-or-many part's or one-or-many lesson's
  • A part can have one-or-many chapter's or one-or-many lesson's

In practice:

src/content/tutorial
├── meta.md # Tutorial
├── lesson-1 # Lesson
└── part-1 # Part

> Error: Cannot mix lessons and parts in a tutorial. Either remove the parts or move root level lessons into a part.

src/content/tutorial
├── meta.md # Tutorial
└── part-1 # Part
    ├── lesson-1 # Lesson
    └── chapter-1 # Chapter

> Error: Cannot mix lessons and chapters in a part. Either remove the chapter from 1-part or move the lessons into a chapter.

However you can have multiple part's, where some contain just chapter's and some contain just lesson's:

src/content/tutorial
├── meta.md # Tutorial
│
├── part-1 # Part with lessons
│   └── lesson-1 # Lesson
│
└── part-2 # Part with chapters
    └── chapter-1 # Chapter
tk-mixed-hierarchy.webm

This comment was marked as outdated.

@AriPerkkio AriPerkkio force-pushed the feat/flat-tutorial-structure branch 8 times, most recently from 977e911 to 8854d0b Compare October 16, 2024 15:18
@AriPerkkio

This comment was marked as outdated.

@AriPerkkio

This comment was marked as outdated.

@AriPerkkio AriPerkkio force-pushed the feat/flat-tutorial-structure branch 2 times, most recently from 5d0cef6 to 1c0694e Compare October 18, 2024 11:54
Copy link
Member Author

@AriPerkkio AriPerkkio Oct 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've pretty much rewritten this whole component. I tried to re-use the old styling as much as possible but there can be something I've missed. Here's comparison of demo.tutorialkit.dev and this PR:

image

@AriPerkkio AriPerkkio force-pushed the feat/flat-tutorial-structure branch 4 times, most recently from 518887e to e76ce9a Compare October 18, 2024 13:30
Comment on lines +40 to +97
You can also omit parts and chapters, if your tutorial doesn't need that deep hierarchy.

<Tabs>
<TabItem label="Structure">
```plaintext
- Lesson 1: Getting started
- Lesson 2: Adding pages
```
</TabItem>

<TabItem label="File tree">
<FileTree>
- src
- content
- tutorial
- getting-started
- _files/
- _solution/
- content.md
- adding-pages/
- meta.md
- config.ts
- templates/
</FileTree>
</TabItem>
</Tabs>

<Tabs>
<TabItem label="Structure">
```plaintext
- Part 1: Introduction
- Lesson 1: What is Vite?
- Lesson 2: Installing
- …
- Part 2: Project structure
- …
```
</TabItem>

<TabItem label="File tree">
<FileTree>
- src
- content
- tutorial
- introduction/
- what-is-vite/
- _files/
- _solution/
- content.md
- installing/
- project-structure/
- meta.md
- config.ts
- templates/
</FileTree>
</TabItem>
</Tabs>

Copy link
Member Author

@AriPerkkio AriPerkkio Oct 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renders to
image

Comment on lines +10 to +13
"dev:lessons-in-root": "astro dev --config ./configs/lessons-in-root.ts",
"preview:lessons-in-root": "astro build --config ./configs/lessons-in-root.ts && astro preview --config ./configs/lessons-in-root.ts",
"dev:lessons-in-part": "astro dev --config ./configs/lessons-in-part.ts",
"preview:lessons-in-part": "astro build --config ./configs/lessons-in-part.ts && astro preview --config ./configs/lessons-in-part.ts",
Copy link
Member Author

@AriPerkkio AriPerkkio Oct 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm planning to create scripts/start.mjs that can be called like node scripts/start.mjs --dev lessons-in-root to reduce these verbose scripts. But that will be added in follow-up PR.

@AriPerkkio

This comment was marked as outdated.

@AriPerkkio
Copy link
Member Author

AriPerkkio commented Oct 22, 2024

/pkg-pr-new

⚡️ Your npm packages are published.
@tutorialkit/astro: npm i https://pkg.pr.new/@tutorialkit/astro@431145a
@tutorialkit/react: npm i https://pkg.pr.new/@tutorialkit/react@431145a
@tutorialkit/runtime: npm i https://pkg.pr.new/@tutorialkit/runtime@431145a
@tutorialkit/theme: npm i https://pkg.pr.new/@tutorialkit/theme@431145a
@tutorialkit/types: npm i https://pkg.pr.new/@tutorialkit/types@431145a

@AriPerkkio AriPerkkio marked this pull request as ready for review October 22, 2024 06:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Parts of only one lesson
1 participant