Integrate Academy

[davehakkens]

The academy is essential for all our communities since it brings the core knowledge to everyone. The academy is setup using an external tool (docusaurs) which has a few problems.

The goal here is to identify the problems and discuss/share possible ways forward to see if it's worth putting on our roadmap.

Current problems

1. Loads in an Iframe which is bad for SEO
2. Hard to make updates for editors and community managers (Need to be done with Github PR)
3. We can’t integrate platform features like comments or useful button.
4. Can't create the function to "login to download" our downloadkit

Things to keep in mind

• The current academy is written in Markdown. This works well for writing documentation. Ideally the platform is able to read this to make migration easier. That said if a change of text editor is needed we can also migrate.
• We’d like to uses either image or video as a header for pages
• Menu needs to be configurable by admins
• We need 3 layers deep submenus’s (example on Precious Plastic > Build> Sheet Press)

Whats needed next

• Technical plan to integrate the academy
• Make a new design based on technical possibilities and limitations

[pizzaisdavid]

2. Hard to make updates for editors and community managers (Need to be done with Github PR)

Github comes with some features, for example: anyone can propose edits, discuss edits, see revision history, and undo changes.

So question to you, Dave, which features of Github, if any, must be supported in order to migrate away from it?

I could imagine a userflow that moves the editing of academy content into the community platform, if that is what you mean by "integrate academy."

Here is the idea:

To edit a page:

1. A community manager logs into community.preciousplastic.com with an admin account.
2. They visit community.preciousplastic.com/academy/build
3. They click the edit button, which is visible only for admins.
4. They are redirected to the page community.preciousplastic.com/academy-admin/edit-page?id=build, it contains:
   -> the id of the page they are editing, as a title (not editable.)
   -> the markdown of the page they are editing, as a textarea.
   -> a submit button.
5. They make changes.
6. They click submit.
7. Their changes are live instantly.

To create a new page:

1. A community manager logs into community.preciousplastic.com with an admin account.
2. They visit community.preciousplastic.com/academy-admin/create-page, it contains:
   -> a text input for the id of the new page.
   -> a submit button.
3. They enter an id (only letters, numbers, dashes, and underscores allowed; if they try something else, they get an error message.)
4. They click submit (if that id is already used, they get an error message.)
5. The page is initialized with empty content.
6. They are redirected to community.preciousplastic.com/academy-admin/edit-page?id=whatever
7. See section above.

To upload a new image:
TBD

To replace an existing image:
TBD

To edit the sidebar:
TBD, I think sidebar is a Docusaurus concept (but I am not sure) so this might have to be re-created in React. But the admin could control the nesting somehow (with some data structure and referencing ids.) Maybe on community.preciousplastic.com/academy-admin/edit-sidebar

To delete pages/images:
TBD, maybe community.preciousplastic.com/academy-admin/dashboard with a list of pages and a list of images, with garbage can icons.

All of these pages (and endpoints that modify data) should require special admin rights.

With this flow above, you also don't have the ability to preview, unless they make changes on a test instance first.

A more complicated flow could also be decided (for example with pending edits and approvals) but that depends on which features are needed.

Given the flow above, I am not sure if Docusaurus could still be used; as it would need to be able to convert markdown content into HTML at runtime (because an admin may come and change the content at any moment.) Maybe it can do that, no idea. Maybe github.com/markedjs/marked would fit requirements, I didn't check.

What I have described does not necessarily address problem 1, 3, or 4, but I imagine it would bring problem 3 one step closer to being solved.

There is a chance that "Integrate Academy" meant something totally different, so let me know if I misunderstood.

(TBD = to be determined.)

[pizzaisdavid]

Assuming I understand correctly, more motivation for going away from iframe: the content inside is not translated via Chrome's translate feature.

source: https://discord.com/channels/586676777334865928/1235195201274777661/1235195201274777661