Transition from Celo Docs to Celo Academy: How to Fix Common Issues

Contributors Sage Program
1

Introduction

We’re thrilled about the move from Celo Docs to the new Celo Academy. However, we’re aware that with any transition, a few hiccups might surface. In this post, we’ll tackle several common issues you may encounter and provide solutions to help you fix them.

Fixing Images

Problem

Broken images or references to hosted images that may soon become unavailable.

Solution:

  • Browse the tutorials for images.
  • If any are broken, locate the image in Celo Docs Tutorials.
  • Download the images.
  • Compress them via TinyPNG.
  • Upload the images to the appropriate tutorial in Celo Academy.

Fixing Headings

Problem

Headings are inconsistently used across tutorials.

Solution

  • Check that all primary headings throughout the post are ## H2 and subheadings are ### H3.
  • Ensure headings are written in lowercase with the first letter of key words capitalized.
  • Example: Use “Welcome to Celo,” not “WELCOME TO CELO” or “Welcome To Celo.”

Fixing Paragraphs

Problem

Paragraph spacing is inconsistent across tutorials.

Solution:

  • Check paragraph spacing in tutorials. If there is a new line, there should be an additional space between the original paragraph and the next.

Fixing Long Posts

Problem:

Due to a post character limit, some posts are broken into replies, making them multiple sections.

Solution:

We have increased the post limit to 3x its original limit. If a post is split up, copy the text of each reply and add them to the original post. Then, delete the replies so that the entire tutorial is contained in a single post.

Fixing Lists

Problem

Bullet point formatting has changed in Celo Academy and is too spaced out.

Solution:

  • Remove the extra space between lists so that they display more compactly.

Fixing Tags

Problem

Tags are inconsistent and don’t currently aid in the discoverability of topics. Celo Academy Tags

Solution:

  • We’ve increased the tag limit from 5 to 7.
  • Identify key areas for tags (tools, languages, industries).
  • Tag all tutorials appropriately (remove celosage, celo tags).
  • Continue to organize tags so they are grouped clearly and enhance the learning experience.

Fixing Installations

Problem

In some cases on common installations @celo has been replaced by @Celo_Academy…

Example

npm install -g @celo/celocli

is now

npm install -g @Celo_Academy/celocli

Soution

Look out for these instances and replace the code with the original command

Fixing Frontmatter

Problem

Posts contain front-matter that was necessary in documentation that we no longer need.

Example

title:
description
authors:
name:
title:
url:
image_url
tags
hide_table_of_contents
slug

Solution

Check for front-matter in posts and remove from the post.

Fixing Tips

Markdown from the documentation for tips does not appear correctly in Celo Academy.

:::tip

Tip here

:::

Solution

You can fix it by changing formatting to that which is supported by Discourse. Remove the ::: and precede the line with >.

Tip here.

Fixing Videos

Video embedding in YouTube is different than it was in the docs. In Celo Academy you only need to paste the full link to embed the video.

Solution

Look for instances of YouTube videos that are not showing in Celo Academy. Remove everything except the video ID and precede it with the following URL https://www.youtube.com/watch?v=

Example: https://www.youtube.com/watch?v=8KlysQOaowU pasted into the editor will show the following:

Thank you!

We’re committed to providing you with a smooth learning experience on Celo Academy. Please use these solutions to mitigate common issues during this transition. As always, we appreciate your understanding and support!

2 Likes