Curriculum File Structure

Our core instructional content is located within the conveniently named curriculum directory. This page will break down how these files are organized.

Terminology

There are a few terms we use when discussing our curriculum content.

• certification : When referring to a certification in this instance, it is talking about the actual certificate that users claim. Which is separate from the name of the superBlock.
• superBlock : A superblock is the top level collection of challenges. Each superblock corresponds to a certification in the curriculum (e.g. Responsive Web Design).
• block : A block is a section within a superblock. A block corresponds to a group of challenges in a given certification (e.g. Basic HTML and HTML5)
• challenge : A challenge is a single lesson within the curriculum (e.g. Say Hello to HTML Elements)

File Tree

Using those terms, here is how the file structure would be defined:

curriculum/
├─ challenges/
│ ├─ english/
│ │ ├─ blocks/
│ │ │ ├─ <block>/
│ │ │ │ ├─ <challenge>.md
│ │ ├─ certifications/
│ │ │ ├─ <certification>.yml
├─ i18n-curriculum/ (git submodule)
│ ├─ curriculum/
│ │ ├─ challenges/
│ │ │ ├─ <language>/
│ │ │ │ ├─ blocks/
│ │ │ │ │ ├─ <block>/
│ │ │ │ │ │ ├─ <challenge>.md
├─ structure/
│ ├─ curriculum.json
│ ├─ superblocks/
│ │ ├─ <superblock>.json
│ ├─ blocks/
│ │ ├─ <block>.json

The Structure Directory

The structure directory contains JSON files that define the curriculum organization and are used to determine which superBlock a block belongs to, and the order of the challenges within that block.

curriculum.json

The main curriculum.json file contains two arrays:

• superblocks: An ordered list of all superblocks in the curriculum
• certifications: A list of all available certifications

superblocks/<superblock>.json

Each superblock has its own JSON file that defines which blocks belong to it. Simple superblocks only contain a blocks array:

{
  "blocks": ["basic-html-and-html5", "basic-css", "applied-visual-design"]
}

More complex superblocks can organize blocks into chapters and modules for better structure:

{
  "chapters": [
    {
      "dashedName": "html",
      "modules": [
        {
          "dashedName": "basic-html",
          "blocks": [
            "workshop-curriculum-outline",
            "lecture-welcome-to-freecodecamp",
            "lab-debug-camperbots-profile-page",
            "lecture-understanding-html-attributes"
          ]
        },
        {
          "dashedName": "semantic-html",
          "blocks": [
            "lecture-importance-of-semantic-html",
            "lecture-understanding-nuanced-semantic-elements",
            "workshop-blog-page"
          ]
        }
      ]
    },
    {
      "dashedName": "css",
      "modules": [
        {
          "dashedName": "basic-css",
          "blocks": [
            "lecture-what-is-css",
            "workshop-cafe-menu",
            "lab-business-card"
          ]
        }
      ]
    }
  ]
}

blocks/<block>.json

Each block has its own JSON file that contains metadata and the order of challenges:

{
  "name": "Basic HTML and HTML5",
  "isUpcomingChange": false,
  "dashedName": "basic-html-and-html5",
  "helpCategory": "HTML-CSS",
  "challengeOrder": [
    {
      "id": "bd7123c8c441eddfaeb5bdef",
      "title": "Say Hello to HTML Elements"
    }
  ]
}

The Certifications Directory

The challenges/english/certifications/ directory contains YAML files that define the certification requirements and project information for each certification.

Each certification YAML file includes the following key properties:

• id: Unique identifier for the certification
• title: Display name of the certification
• certification: Internal name used to reference the certification
• tests: Array of required projects with their IDs and titles

Internationalization Structure

The curriculum content is internationalized using a git submodule located at curriculum/i18n-curriculum/. This submodule contains translated versions of curriculum content:

• English content: Located directly in curriculum/challenges/english/
• Translated content: Located in the submodule at curriculum/i18n-curriculum/curriculum/challenges/<language>/

The structure within each language directory mirrors the English structure exactly, with the same block folders and challenge files. However, only the Markdown challenge files (.md) are translated and stored in the i18n-curriculum submodule. Configuration files such as YAML certification files and JSON structure files remain in English only.

The i18n-curriculum submodule is updated automatically. Manual changes to translated content should not be made directly in the submodule.

Renaming Files

There may be times when you need to rename a certificate, superblock, block, or challenge. This section will outline the steps needed to avoid build errors when doing so.

Danger

Renaming files within the curriculum structure will often change the path (or URL) of the content on the main webpage. Doing so should be done with care, as redirects have to be set up for each change that is made.

Setting Up Redirects

When renaming curriculum items that change URLs, you must set up redirects to ensure existing links continue to work. This requires updating two serve.json files with identical redirect configurations:

1. Client Configuration: /client-config/serve.json
2. Main Application: /client/serve/serve.json

Both files contain a "redirects" array where you need to add redirect objects. The redirect format follows this pattern:

{
  "source": "/learn/old-name/:param?",
  "destination": "/learn/new-name/:param?"
}

URL Parameters:

• :superblock? - Captures superblock name (optional)
• :block? - Captures block name (optional)
• :challenge? - Captures challenge name (optional)

Examples:

For superblock renaming (e.g., apis-and-microservices → back-end-development-and-apis):

{
  "source": "/learn/apis-and-microservices/:block?/:challenge?",
  "destination": "/learn/back-end-development-and-apis/:block?/:challenge?"
}

For block renaming within a superblock:

{
  "source": "/learn/responsive-web-design/old-block-name/:challenge?",
  "destination": "/learn/responsive-web-design/new-block-name/:challenge?"
}

For individual challenge renaming:

{
  "source": "/learn/superblock/block/old-challenge-name",
  "destination": "/learn/superblock/block/new-challenge-name"
}

Both serve.json files must be updated with identical redirects. The redirect setup must be done in a separate PR that gets merged AT THE SAME TIME as the PR that actually renames the curriculum items. This ensures the redirects go live simultaneously with the URL changes, preventing any broken links.

Renaming a Certification

When renaming a certification, you will likely want to rename the associated superblock along with it. Do the following to rename only the certificate:

1. Rename the curriculum/challenges/english/certifications/<certification>.yml file to the new name.
2. In the YAML file, change the title to the new name.
3. Update the certifications array in curriculum/structure/curriculum.json to use the new certification name.
4. Update client/src/redux/index.ts to use the correct title.
5. Optionally, update the certSlug for the superblock in the same file. (Note: Renaming a certSlug will change the URL for certifications and should only be done with careful consideration.)
6. If you renamed the certSlug, add redirects to both serve.json files (/client-config/serve.json and /client/serve/serve.json) to redirect from old certification URLs to new ones:

   {
     "source": "/certification/old-cert-slug",
     "destination": "/certification/new-cert-slug"
   }

7. Update the title in client/src/resources/cert-and-project-map.ts to the new value. (Note: Changing the title here will break the superBlock page for the associated certification. It relies on the superBlock title to match the certification title. You will likely want to rename the superBlock at the same time.)
8. If you renamed the certSlug in step 5, change it here for the cert and all the nested projects values.
9. In shared/config/certification-settings.js, update the value of certTypeTitleMap to the new name.
10. In shared/config/certification-settings.js, update the value of certTypeTitleMap to the new name.
11. If you renamed the certSlug in step 5, update the key of certSlugTypeMap in the same file.
12. Update the certificate name in the legacyCerts array of the client/src/client-only-routes/show-project-links.tsx if needed.
13. Update the main README.md file to the new name.

Note

Translated content in the i18n-curriculum submodule will be updated automatically and does not require manual intervention.

Renaming a Superblock

Note

When you rename a superBlock, the new folder name is used as the path and should be considered the “correct” name. All other values should be updated to reflect that change.

Also, you will likely want to rename the certificate and the <superBlock>-projects block when you rename a superBlock since they all share a name. To rename only a superBlock you need to:

1. Rename the superblock file in curriculum/structure/superblocks/ from <old-name>.json to <new-name>.json.
2. Update the superblocks array in curriculum/structure/curriculum.json to use the new superblock name.
3. For each block within that superBlock, update the superBlock value in their respective JSON files in curriculum/structure/blocks/ to the new dashedName.
4. Add redirects to both serve.json files (/client-config/serve.json and /client/serve/serve.json) to redirect from old superblock URLs to new ones:

   {
     "source": "/learn/old-superblock-name/:block?/:challenge?",
     "destination": "/learn/new-superblock-name/:block?/:challenge?"
   }

5. Rename the superblock folder in client/src/pages/learn.
6. Update the index.md file in the renamed superblock folder, changing the title and superBlock values to the new name.
7. For each block folder within the above, update the index.md to use the correct superBlock value.
8. For each block folder within the above, update the index.md to use the correct superBlock value.
9. In the client/src/resources/cert-and-project-map.ts file, update the path for the cert at the top of the file, and the title value for that superBlock. (Note: Changing the title here will break the ability to view the actual certification for this superBlock. It relies on the superBlock title to match the certification title. You will likely want to rename the certification at the same time.)
10. Update the superBlockCertTypeMap key in shared/config/certification-settings.js to the new superBlock name.
11. Update the path value in client/src/assets/icons/index.tsx.
12. For each language in client/i18n/locales, update the intro.json file to use the new superBlock dashedName. In the English file, also update the title.
13. Check the shared/config/i18n/all-langs.js file to see if the superBlock is enabled in i18n builds. Update all the values where it is used.
14. Update the superBlockNames map in curriculum/build-curriculum.js. This map links superblock filenames (keys) to certification names (values) - update the key if the superblock filename changed, and update the value if the certification name changed.
15. Update the main README.md file to the new name.

Renaming a Block

When renaming a curriculum block, you need to:

1. Change the name of the block folder in the curriculum/challenges/english/blocks/<block> directory.
2. Rename the block’s JSON file in curriculum/structure/blocks/ from <old-name>.json to <new-name>.json.
3. Update the name and dashedName properties in the renamed block JSON file.
4. Update the superblock’s JSON file in curriculum/structure/superblocks/ to reference the new block name in its blocks array.
5. Add redirects to both serve.json files (/client-config/serve.json and /client/serve/serve.json) to redirect from old block URLs to new ones:

   {
     "source": "/learn/superblock-name/old-block-name/:challenge?",
     "destination": "/learn/superblock-name/new-block-name/:challenge?"
   }

6. Update the block folder in client/src/pages/learn/<superBlock>.
7. In the index.md file of the above folder, update the block value in the frontmatter.
8. In the client/i18n/locales/<language>/intro.json files, update the block name to the new name for all the languages. In the English intro.json file, update the title as well.
9. In the client/i18n/locales/<language>/intro.json files, update the block name to the new name for all the languages. In the English intro.json file, update the title as well.
10. Update the main README.md file to the new name.

Note

Translated content in the i18n-curriculum submodule will be updated automatically and does not require manual intervention.

Renaming a Challenge

When renaming a single challenge file, you need to:

1. Change the name of the challenge file in the curriculum/challenges/english/blocks/<block>/ directory.
2. Change the name of the title and dashedName within that file.
3. Update the challenge title in the relevant block JSON file in curriculum/structure/blocks/<block>.json. The challenge names in the challengeOrder array are used in the build and provide the order of challenges.
4. Add redirects to both serve.json files (/client-config/serve.json and /client/serve/serve.json) to redirect from old challenge URLs to new ones:

   {
     "source": "/learn/superblock-name/block-name/old-challenge-name",
     "destination": "/learn/superblock-name/block-name/new-challenge-name"
   }

5. If the challenge is a certificate project, update the YAML file in curriculum/challenges/english/certifications/<certification>.yml to the new name.
6. If the challenge is a certificate project, update the title and link in client/src/resources/cert-and-project-map.ts
7. If the challenge is a certificate project, update the main README.md file to the new name.
8. If the challenge is a certificate project, update the main README.md file to the new name.

Note

Translated content in the i18n-curriculum submodule will be updated automatically and does not require manual intervention.

The dashedName Property

The dashedName property is used to generate the URL path for the superblock, block, or challenge. These should generally match what the /utils/slugs.js helper would output for the file name.