wordpress / learn

WordPress.org Learn - The canonical source for the code and content behind https://learn.WordPress.org

WP - Learn WordPress

The details below will walk you through getting set up to contribute to the code behind https://learn.wordpress.org. If you are interested in contributing to the content or translation of the content hosted on the site, you'll find further guidance in the Training Team Handbook. Content development is tracked on this GitHub repository in this project board.

Getting Started Workshops

If you're interested in contributing to the site, but aren't sure where to start, we have a series of workshops to help you get started.

• Contributing to Learn WordPress with code – part 1
• Contributing to Learn WordPress with code – part 2

Prerequisites

• Docker
• Node/NPM
• Yarn
• Composer
• SVN
• NVM or N (optional)

Setup 2020 version

1. yarn
2. yarn run create:old
3. Visit site at localhost:8888

Setup 2024 version

1. yarn
2. yarn run create
3. Visit site at localhost:8888
4. To watch for changes yarn start:theme

Stopping Environment

run yarn run wp-env stop

Removing Environment

run yarn run wp-env destroy

Admin

Since the local environment uses wp-env, it automatically comes with an admin user, with admin/password for the credentials.

Development

While working on the theme & plugin, you might need to rebuild the CSS or JavaScript.

To build all projects, you can run:

yarn build

To build one project at a time, run:

yarn workspace wporg-learn-2024 build
yarn workspace wporg-learn-theme build
yarn workspace wporg-learn-plugin build

If you want to watch for changes, run start. This can only be run in one project at a time:

yarn workspace wporg-learn-2024 start
yarn workspace wporg-learn-theme start
yarn workspace wporg-learn-plugin start

Linting

This project has eslint, stylelint, and phpcs set up for linting the code. This ensures all developers are working from the same style.

To lint everything run:

yarn lint

To lint one language run one of:

yarn lint:js
yarn lint:css
yarn lint:php

To check an individual project before pushing to the repo, run one of:

yarn workspace wporg-learn-2024 lint:css
yarn workspace wporg-learn-2024 lint:js
yarn workspace wporg-learn-theme lint:css
yarn workspace wporg-learn-plugin lint:css
yarn workspace wporg-learn-plugin lint:js
composer run lint

Linting will also be run automatically on each PR.

Contributing

If you'd like to contribute to the project, please read the Developing Learn WordPress page in our team handbook.

learn's Issues

Workshop Details block: editor script causes whitescreen when minified

Then the script for the workshop-details block is built with wp-scripts build, the code is minified, and when it loads in the editor, you get a white screen of death. Curiously, the errors in the console relate to Jetpack, rather than our plugin. Nevertheless, if you disable our block, everything works again.

If the block script is instead built with wp-scripts start, the code is not minified, and no white screen of death occurs. 🤷‍♂️

Workshop page Url should be `workshop/{id}`.

It currently is /wporg_workshop/{id}.

Workshops: Turn the right column blocks in the template into a reusable block

If possible, it would be ideal if the right column of the workshop template, which includes the Workshop Details block, a "Join a discussion group" button block, and a paragraph block about the code of conduct, could be saved as a reusable block, since that content should be the same on all workshops. And then put that reusable block in the template. That way all existing workshops and new ones could have that content updated all at once, if, say, the link in the "Join a discussion group" button ever needed to be updated.

Lesson plans: Disable functions that add links/references to GitHub

Importing lesson plan markdown from GitHub has been disabled, but there are places in the plugin, and perhaps the theme, where links and other references to the GitHub repo are showing up. One example is WPOrg_Learn\LessonPlan::get_markdown_edit_link(). These should be disabled or removed as well, since the canonical source of the lesson plan content is now the WP site.

PHP Warnings due to Markdown importer

E_WARNING: wp-content/plugins/wporg-learn/inc/class-markdown-import.php:168 - in_array() expects parameter 2 to be array, string given

https://github.com/WordPress/learn/blob/trunk/wp-content/plugins/wporg-learn/inc/class-markdown-import.php#L15 is supposed to be an array (based on it's name, and how it's used), but is a singular string.
Either that should be set to an array, or all the in_array()'s should be swapped to direct matches.

However, it's also later also used as a string: https://github.com/WordPress/learn/blob/trunk/wp-content/plugins/wporg-learn/inc/class-markdown-import.php#L96

Fix some of the awkward styles

• Some titles are underlined, they shouldn't be.
• Lesson Plan: Checkboxes list have bullets, shouldn't.

Workshop Presenter Application Form

To aid in the vetting and approval of applications to be a Workshop presenter, I'd like to propose a form be setup to create a Workshop Post Type (#3) with an initial, unpublished, post status. The implementation would be similar to the CPTs in place for WordCamps and Meetups on central.wordcamp.org. This WordCamp Application Class code may be useful to review.

The current form asks questions that are good for vetting and approval for the presenter to start creating their video. The WordCamp organizer form lives at https://central.wordcamp.org/wordcamp-organizer-application/. For the Workshop presenter application form, I'd propose it live at https://learn.wordcamp.org/workshop-presenter-application/.

I believe there should be a series of Workshop post statuses setup as well. I've reviewed the list of WordCamp post statuses and propose the following:

• Needs Vetting
• More Information Requested
• Declined
• Approved to Create Video
• Needs Video Review
• Workshop Published
• Workshop Unlisted

The Workshop Unlisted status could have a different name. It would be used to indicate a Workshop has been removed typically because the content is no longer accurate.

Some questions that might determine other statuses to consider:

• Should there be a separate status to put a update the title and description?
• Does a Workshop Presenter need to sign an agreement?
• Are there other statuses which should be considered?

Integrate speaker feedback tool

The speaker feedback tool was built for WordCamps. It would be great to activate it on the Learn site for workshops. https://make.wordpress.org/community/handbook/wordcamp-organizer/speaker-feedback-tool/

CC @coreymckrill

Home: Add Recent Workshops

https://www.figma.com/file/UtmG8KQv3Csy8hNtuAWkwZ/Learn-WordPress?node-id=39%3A39

Workshop submission flow

Since we're just getting started with all this, we're using a Crowdsignal form to accept submissions. Ultimately we would need this to be more integrated into the site, so here's a proposal for how that flow could work:

Step 1: Presenter submits their workshop details in a custom form. This saves their details as a new post in the workshop CPT, but in draft status (ref #3 for the post type discussion).

Step 2: Reviewers are given a user role that permits them to edit posts in the workshop CPT (editor? A custom user role?). They can log in to review the workshop and leave notes on it as needed.

Step 3: For a workshop that is approved, the reviewer would get any additional info from the presenter, and also inform them that they should go ahead and record the workshop.

Step 4: The recorded workshop, along with any other missing info, is added to the post and it is scheduled to be published.

As you can see, this would work in a similar way to how WordCamp sessions are submitted since they are saved in draft status until approved and complete. It would also need to have the notes feature that WordCamps and meetups have on central.wordcamp.org.

How does this sound? I don't expect this to be ready for the launch on 12 August, since we can continue with the Crowdsignal form in the meantime, but it would be good to have this done as soon as possible afterwards.

/cc @StevenDufresne @coreymckrill

Workshops: Change the Captions field to a multi-select with locales as options

Similar to #49, the Captions field would be better as a select element with a list of locales. The only difference here would be that you could select more than one locale, and also remove a previously selected locale via the UI.

Alter the homepage title

The <title> tag content is currently "WordPress.org".
It should be "Learn WordPress".

Home: Small Layout/Design tweaks

https://www.figma.com/file/UtmG8KQv3Csy8hNtuAWkwZ/Learn-WordPress?node-id=39%3A39

Features

• Change Parallelograms from "Workshop Ideas" -> "Workshops"
• Change "Have a workshop" callout.

Lesson Plans need categories

The lesson plan archive is incomplete. The lesson plan archive will pull in lesson plan categories and make them available in the "navigation" bar. Lesson plans are then displayed if they match categories. Since we don't automatically create categories, nor have lesson plan assigned, no lesson plans are visible.

Maybe the quickest route is to add an "All" category and after import assign them all to that category?

Workshop template doesn't match

I browsed to https://learn.wordpress.org/wp-admin/post.php?post=505&action=edit on production and saw the following message:

The content of your post doesn’t match the template assigned to your post type.
Screenshot:

Add excerpt support to workshops

The workshop CPT does not support excerpts, so the search results only show the title. Please add excerpt support to the workshop CPT so we can dd the short descriptions in there.

Home Page buckets are not linked

The buckets of content & links are not linked to anywhere. When addressing this, we should make sure the copy matches the links seeing that the copy reflects a post MVP state when there are advanced filters and numerous workshops. We only plan on launching with a couple and without advanced filtering.

Screenshots

Hide "Captions" on frontend if none exist

The workshop details on the frontend show an item labelled "Captions" - this should be hidden if no captions are added to the workshop post.

Workshops Archive

Filter UI:

https://www.figma.com/file/UtmG8KQv3Csy8hNtuAWkwZ/Learn-WordPress?node-id=51%3A3565

Features

Milestone 1

• Workshop list

Milestone 2

• Search
• Filters
• Advanced Features

Search results: Differentiate between CPTs

The search function searches the lesson plans and the workshops, but they are displayed in a single list with no visual distinction - example: https://learn.wordpress.org/?s=block

Could this be updated to show some sort of visual differentiator? Either a highlight of some kind or, better yet, display results in two columns/areas - one for each CPT.

Theme: Form is not made for typos

Copied from https://meta.trac.wordpress.org/ticket/5372

If a typo error is found, there is a link to the form https://wordcampcentral.survey.fm/learn-wordpress-workshop-application

That form is not really meant for sharing errors on the site.

Presenter Style: The CSS is not being applied.

Description

Locally, the styles are being applied. On learn.wordpress.org the presenter is not getting its style.

Either there is a conflict or the CSS should be rebuilt.

Screenshot

Learn.wordpress.org INCORRECT	localhost:8888 CORRECT

You can verify that the changes work by making sure the img tag has the .workshop-presenter_profile class.

Title tags should end in "Learn WordPress", not "WordPress.org"

Page titles end in " | WordPress.org", which results in a lack of differentiation from the main / other WordPress sites.
To address this, titles should instead end in " | Learn WordPress".

Submit idea button goes to 404

The button for submitting a workshop idea goes to a 404 page. This would be valuable to keep in so we can get suggestions for workshops people would like to see.

Theme: Header template is throwing a PHP notice on some views

Notice: Undefined variable: home_page in /home/wporg/public_html/wp-content/themes/pub/wporg-learn-2020/header.php on line 32

It looks like the $home_page variable is only defined when the view is of the home page...

Duration is too verbose.

I don't think we need to show the duration with complete accuracy. Users can get that from the video. I see it more as a "2 min read" experience where you are just glancing at it to have a rough sense of how long it would take.

Screenshot

Solution

I think we can say:

1. Under 1 hour?
   -> "43 minutes"

2. Over 1 hour?
   -> "1 Hour, 43 minutes."

3. Between 24 & 48 hours?
   -> "1 day" (round up?)

The last one may not apply.

I think we don't ever show seconds.

Normalize text domains

Between the plugin and the theme, the codebase is using several different text domains. We should standardize on one. I would suggest wporg-learn.

Local Dev: WordPress database error: [Table 'wordpress.locales' doesn't exist]

I setup my local environment on Docker v19.03.12 with Node v.12.18.3 and Composer v1.10.10. When browsing to http://localhost:8888/ I see the following error across the top of page. This error does not prevent the rest of the page to render. The error shows up in the browser's source just before the </head> tag.

WordPress database error: [Table 'wordpress.locales' doesn't exist]
SELECT locale, subdomain FROM locales

The output of the npm run create is attached: learn-npm-run-create.log

Workshops: Change the Language field to a single-select with locales as options

Instead of an open text field, which is prone to typos and other user errors, the language field would work much better as a select element with a list of locales, where the label of each option is the name of the locale (e.g. Spanish (Mexico) ) and the option value is the ISO code (e.g. es_MX). Ideally the select would have functionality like Select2, where you can begin typing to search and narrow down the list of available choices.

Featured image for workshops

Right now, if a featured image is not set for a workshop then nothing is displayed on the frontend. Could this be changed so that, if a featured image is not set, a default generated thumbnail is displayed? Like what you see on the homepage of WPTV: https://wordpress.tv/

Workshop Single Template

https://www.figma.com/file/UtmG8KQv3Csy8hNtuAWkwZ/Learn-WordPress?node-id=15%3A1390

Local Dev: 404 pages; resolved with permalink flush

I setup my local environment today and saw a 404 error on these pages:

• http://localhost:8888/lesson-plans/
• http://localhost:8888/workshops/

I went to the Permalink Settings page and saw the option Post name was already selected. Once I saved the changes I was able to browse to both of the pages I mentioned earlier without issue.

Archive: Submit CTA on archive page shouldn't have the lightbulb icon.

The lightbulb icon should only show up on the homepage as per the designs.

https://www.figma.com/file/UtmG8KQv3Csy8hNtuAWkwZ/Learn-WordPress?node-id=106%3A0

Workshops Landing Page

https://www.figma.com/file/UtmG8KQv3Csy8hNtuAWkwZ/Learn-WordPress?node-id=14%3A598

Features

Milestone 1

• Featured Workshop
  • Video
  • Title
• Recent Workshops grid

Milestone 2

• Featured Workshop Video Author Info
• Paging

Project Proposal

Purpose

To agree on an approach to support the new workshop post type and implement the designs shown here:
https://www.figma.com/file/UtmG8KQv3Csy8hNtuAWkwZ/Learn-WordPress?node-id=0%3A1

Proposal

We can leverage the learn theme beta project because ultimately it's where these workshops will probably live.

Background Info

The learn theme beta currently has 2 custom post types:

1. lesson-plan (Link)
2. workshop (Link)

The post types share taxonomies:

Taxonomy	Example	Notes
Categories	Popular	Used for filtering on lesson-plan/workshop browser (See Learn designs)
Audience	All
Duration	1 Hour
Experience Level	Beginner
Instruction Type	Presentation
Lesson Group	Security	This taxonomy is used to tie lesson-plans together so they can be added to different workshop ideas. Add lessons to a lesson group, add the lesson group to the workshop.
Topics	Dashboard Overview, What you can do with WordPress	This only exists for workshop post type.

Suggestions:

I think we should turn off the current workshop with the aim of adding it back in later (as workshop-ideas maybe). We then create a new plugin that registers a workshop post type.

Tasks:

1. Remove references to current workshop, effectively disabling it. (We could move it into its own plugin.)
2. Create a new plugin with workshop Custom Post Type for new workshops

Home page CTAs

There needs to be a couple of changes to the home page CTAs:

1. Swap the lesson plans and browse workshop CTAs around, so the workshops appear first and the lesson plans second.
2. The description for the workshops CTA must change to this:

Workshops are a great way to get hands-on with WordPress. Here are some workshops for you to level up your WordPress skills.

Workshop presenter area needs to be dynamic

I assume this is still being worked on, but the workshop presenter details are currently hard-coded and need to be generated from the presenter's .org profile instead. Example at the bottom of this page: https://learn.wordpress.org/wporg_workshop/intro-to-publishing-with-the-block-editor/

Link for discussion groups

Please could you link all the "Join a discussion group" buttons and links to this URL: https://www.meetup.com/learn-wordpress-discussions/events/

Theme: Implement page navigation in the blue header bar

Splitting this out from #21

Workshop duration/length

I added a workshop here using real data: https://learn.wordpress.org/wporg_workshop/intro-to-publishing-with-the-block-editor/

The "duration" options in the dashboard offer hour and minute inputs, but since many workshops will be under 1 hour, an input for 'seconds' would be useful too.

On the frontend, the length is displayed as a number here - in this case "2340", which is the number of seconds in the 39 minutes I set for this workshop. It looks like that just needs some time formatting.

Theme: Too much empty space after description

Copied from https://meta.trac.wordpress.org/ticket/5371

On smartphone the lessons present pretty okay, but on tablet or laptop, there is too much empty space.
Possible solutions:

1. Show a longer description
2. Reduce the size of the boxes

Add sub-categories as drop-down menus on lesson plan filters

The lesson plan filter shows all the parent categories by default: https://learn.wordpress.org/lesson-plans/ - would it be possible to add sub-categories as drop-down menus for each one? This would only need to be in a future iteration.

Integration: Install theme/plugins on .org

Particularly interested in seeing style/class conflicts.

Workshop Post Type

https://www.figma.com/file/UtmG8KQv3Csy8hNtuAWkwZ/Learn-WordPress?node-id=15%3A1390

Features:

• Video
• Video Meta data
• Content
• Author Informaton
• Join Discussion -> Forum support

Excerpt from tardis regarding content:

Each workshop post will need to have:
Title
Description
Video (this could be either from WPTV or YouTube)
A set of comprehension questions
A set of learning outcomes
Presenter's .org username (this will then need to fetch their name and avatar for display)

We should probably write these as blocks within a post template?

Questions:

• Where do the videos live?
• Do we have a plugin for the video player?
• Should we write the video player component as a Gutenberg block?

Title and intro text

The current title text of "Help Others Learn WordPress" must be changed to simply "Learn WordPress" - this appears on the home page as well as in the header on all sub-pages.

The intro text below that title on the homepage must be changed to:

Whether you’re a first-time blogger or seasoned developer, there’s always more to learn. From the contributors who make WordPress, these vast resources will help you learn more about WordPress and teach it to others.

Integrate Meetings calendar plugin

The Make Meetings calendar uses a custom plugin: https://make.wordpress.org/meetings/ - could we activate that on Learn? We could use it for the discussion group sessions to show when they'll be happening.

CC @tellyworth

Theme: Breadcrumbs not always shown

Copied from https://meta.trac.wordpress.org/ticket/5373

https://learn.wordpress.org/lesson-plan/high-level-overview/ is showing breadcrumbs correctly, but clicking on 'Lessons Plans', the breadcrumbs disappear.

Setting up your environment

For fast configuration, grab this repo:

https://github.com/StevenDufresne/wp-learn-starter

Video Grid Item: Support clicking image for navigation.

Right now the link under the image will lead you to the workshop. You should be able to click the image as well. I didn't wrap the image within the because I don't think that's great for accessibility. Will revisit.

Workshops: Auto-generated excerpts will always be empty

In #33 we're enabling excerpts for our workshop post type so that it can be used to show a summary of the workshop content in other places on the learn site where a workshop might be featured or called out. However, the excerpt_remove_blocks function that gets called during excerpt auto-generation is stripping out all of the workshop content, leaving a blank excerpt. This is because we're using core/group blocks in our content template, which excerpt_remove_blocks does not support (even though it supports core/columns). There's a Core ticket about this issue, so it this behavior may change eventually, but in the mean time, we'll need to ensure that all featured workshops have a manual excerpt.

I'm opening this issue to document why our excerpts are blank, and provide a space to discussion alternative solutions (or inspire someone to submit a Core patch!)