Issue Description

Information is outdated

URL of the Page with the Issue

https://wordpress.org/support/article/wordpress-features/

Section of Page with the issue

https://wordpress.org/support/article/wordpress-features/#at-a-glance
https://wordpress.org/support/article/wordpress-features/#broadcast-your-ideas

Why is this a problem?

The information and links are outdated

Suggested Fix

from @estelaris "change ""more than a quarter"" for ""almost half"".
"" WordPress isn’t even used as a blog"" links to an article written in 2011
Feeds section's links are very old, is there any updated information regarding feeds?"

from @atachibana "[About feed] WordPress used to create the closed network with feed or comment, but SNS changed it, and now WordPress is a kind of conent repository accessed by REST. We can remove the external links to feed.
[Additional editorial] We should remove this sentence because we have to maintain this page every year -- ""With more than 50 million sites globally and 13 years of proven history, you know you’re getting the best software for the job."""

Issue Description

Block editor end user docs has manually added changelog for every new edit on the article. This is very helpful, especially for translators when updating articles in their locales.

First part of this issue is to apply this practice to the rest of documentation managed directly in WordPress - the rest of HelpHub and parts of DevHub (Plugin, Theme, Common APIs Handbooks).

Second part of the issue is that we can expect to come to the point in time when this changelog will be longer than the content itself. We don't want that so we need to think of a better way to do it. Perhaps the quick solution could be placing it on the second page using <!--nextpage--> tag.

Third part of the issue is making everything automated. Before Gutenberg HelpHub had Enhanced Revisions plugin which allowed adding a short message for the update. If something like this can be restored and used on frontend to show dates and messages that could be extremely useful and time saving.

Why is this a problem?

It is unknown when was the last content update and how current it is. Also, this would make life so much easier for locale translators.

Suggested Fix

Let's discuss about possible ways to add changelog wherever needed/possible, how to do it and how to automate it.

This issue was moved from HelpHub issue #307 by GeoJunkie and ma0sm.

1. issue opened by GeoJunkie

Issue Description

In the HTTP API doc, the link to Basic Authentication with the WordPress HTTP API is outdated. Current linked document was 301 redirected to the document's current location, but that 301 is gone now and the link is broken. (Source: archives.org).

Context

Found this while learning the HTTP API, and it took some work to locate.

The link should be changed from http://lud.icro.us/wordpress-http-api-basicauth/ to https://johnblackbourn.com/wordpress-http-api-basicauth/

Steps to reproduce:

1. Go to External References section of HTTP API documentation
2. Click on the Basic Authentication with the WordPress HTTP API link

Expected Result:

Read about basic documentation with the WordPress API

Actual Result:

Server Not Found

2. Comment by ma0sm.

https://developer.wordpress.org/apis/handbook/http/#external-references doesn't seem to be a valid URL, nor is the one to the HTTP API doc (https://developer.wordpress.org/apis/handbook/http/)

Navigating to Core Contributor Handbook and then Contribute with Docs leads me to this page which is empty
https://make.wordpress.org/core/handbook/docs/

It probable should directly link to: https://make.wordpress.org/docs/handbook/

This issue was moved from HelpHub issue #312 reported by ptrkcsk.

1. issue opened by ptrkcsk.

Issue Description

The Heartbeat API page says:

When the page loads, the client-side heartbeat code sets up an interval (called the “tick”) to run every 15-60 seconds

As far as I can tell, the upper bound on the interval is 120 seconds when the tab is blurred (source).

It looks like this was most recently changed (from 100 to 120 seconds) in #25073, released with WP v3.8.

Context

I spent several hours debugging an issue while under the assumption that the Heartbeat interval would not be longer than 60 seconds.

Steps to reproduce:

1. Visit https://developer.wordpress.org/plugins/javascript/heartbeat-api/

Expected Result:

When the page loads, the client-side heartbeat code sets up an interval (called the “tick”) to run every 15-120 seconds

Actual Result:

When the page loads, the client-side heartbeat code sets up an interval (called the “tick”) to run every 15-60 seconds

2. comment added by ptrkcsk.

Apologies in advance if this is not the right place for this. It's difficult to tell how to contribute content changes to the Plugin Handbook.

Document how to setup code linting / fixing in IDE for following WordPress coding standards

Hi,
I think it would be great to have a go-to doc for all tools recommended for linting PHP, JS, CSS etc to follow WP coding standards.

Including how to setup and utilize this linting in the most popular IDE's (vscode, phpstorm)

Linting php: wp-coding-standards/wpcs
Linting js / css / md / json: npm packages in gutenberg, @wordpress/scripts includes the things needed, but the eslint / prettier / csslint etc. setup could maybe be extracted from this, so you can use it in your own build tools / even if you don't use build tools.

How will this new page help you?

I would hope it could help plugin and theme developers with writing code the WordPress way. And give an onramp for core contributors.
I also think it would help WordPress agencies as a go-to guide for new hires.

Issue Description

Some end-user docs are too technical and are reflective of a by-gone era where some hosts simply failed at supporting WordPress. Hence needing us to provide documentation.

e.g. https://wordpress.org/support/article/using-permalinks/ starts talking about htaccess etc. Really, we ought to just be telling the end-user to contact their host and work it out - perhaps with a recommended text.

URL of the Page with the Issue

https://wordpress.org/support/article/using-permalinks/

Section of Page with the issue

Why is this a problem?

I believe the technical bits (not just in this link) confuses end users.

Suggested Fix

Reassess all pages with technical bits and move those to DevHub if necessary.

How to work on these articles

What is too technical? Roughly explained:

1. no code except for wp-config.php file
2. only what can be done in wordpress dashboard
3. no hosting provider specific docs, no server configuration etc

What's next?

1. Pick up an article via creating an issue
2. If you create an issue we assume you're working on it
3. When you're ready, via the Projects link, push it into the Content Review Column
4. One of us will review it for "official stamping", any others can provide suggestions, it's open source
5. Once the content is verified to be good, it needs to be pushed into the Implementation column so teh content can be transcribed to WordPress.org
6. After implemented, the issue needs to be pushed into the Style Guide review column so that someone can apply/review if the article is following the style guide

Project board: https://github.com/WordPress/Documentation-Issue-Tracker/projects/2

Issue Description

The theme.json backward compatibility equivalences list contains wrong information.

URL of the Page with the Issue

https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#backward-compatibility-with-add_theme_support

Section of Page with the issue

Section: "Backward compatibility with add_theme_support"
Look at the table's first row.

Why is this a problem?

The "theme.json setting" column value of the first row is wrong:
"Set typography.customLineHeight to false."

Suggested Fix

The correct text should be:
"Set typography.customLineHeight to true."

Issue Description

The documentation containing instructions to edit permalinks is too technical and many hosting platforms now limit SSH access. The new documentation should show users how to use the Settings > Permalink feature of WordPress@latest.

Note: SFTP is a viable option, but not for wysiwyg (non-API) users.

Linked to #30

URL of the Page with the Issue

https://wordpress.org/support/article/using-permalinks/

Section of Page with the issue

https://wordpress.org/support/article/using-permalinks/#using-pretty-permalinks
https://wordpress.org/support/article/using-permalinks/#fixing-permalink-problems
https://wordpress.org/support/article/using-permalinks/#tips-and-tricks

Why is this a problem?

Because this is too technical for front-end wysiwyg users.

Suggested Fix

1. Remove all documentation instructing users to edit .htaccess by hand.
2. Leave the instructions on how to update .htaccess automatically — rename it to "Updating your Permalinks".

Correct instructions: https://wordpress.org/support/article/using-permalinks/#automatically-updating-htaccess

On https://developer.wordpress.org/rest-api/reference/users/, there are duplication on the topics list for entries: "Update a User", "Retrieve a User", "Delete a User".

I would suggest distinguish between them by change them to, e.g., "Update Any User" or "Update a User by ID" and "Update the User Currently Logged In".

A few suggestions on https://developer.wordpress.org/themes/basics/template-hierarchy/ (from a person who's learning WP and reading WP docs for the first time).

1. Fix the link on "query string", which currently points to a (non-anchored) "This page was moved to" page.

2. Update the explanation regarding the query string and how it relates to finding the right template.
   As currently I read:

"WordPress uses the query string to decide which template [..] should be used to display the page. [..] It comes after the initial question mark and may contain a number of parameters separated by ampersands."
Many (if not most?) WP websites use URLs without question marks or ampersands. So, this explanation is puzzling.

3. A note about child templates would be nice, as currently, that hierarchy description (and the examples) is considering only a stand-alone themes.

Issue Description

Several multilingual plugins mentioned in the Multilingual WordPress page aren’t maintained anymore and could probably be removed from the article.

URL of the Page with the Issue

https://wordpress.org/support/article/multilingual-wordpress/

Section of Page with the issue

Introduction and Different types of multilingual plugins sections

Why is this a problem?

New WordPress users looking for a multilingual plugin and reading this article might start using a deprecated plugin.

Suggested Fix

Replace the following plugins mentioned:

Qtranslate-x (https://wordpress.org/plugins/qtranslate-x/)
by
Qtranslate-xt (https://github.com/qtranslate/qtranslate-xt)

Global Translator (https://wordpress.org/plugins/global-translator/)
by
Weglot (https://wordpress.org/plugins/weglot/)

Remove the following mentions:
Zanto (https://wordpress.org/plugins/zanto/)

Full disclosure - I work at Weglot

This issue was moved from HelpHub issue #314 reported by oskar-fagerfjall.

Issue Description

In the Shortcodes with Parameters chapter in the plugin handbook, the complete example at the end is incorrect. It works fine for shortcodes without content, but when adding content that content is echoed twice.

Context

The problematic code is the following

    if ( ! is_null( $content ) ) {
        // secure output by executing the_content filter hook on $content
        $o .= apply_filters( 'the_content', $content );
 
        // run shortcode parser recursively
        $o .= do_shortcode( $content );
    }

This code appends the content variable to the output twice, once without running the shortcode parser recursively, and once without properly securing the output.

Steps to reproduce:

1. Copy the example code into a plugin
2. Activate the plugin
3. Make a new post containing [wporg title="A"][wporg title="B"]test[/wporg][/wporg]
4. Preview the post

Expected Result:

The shortcode should result in

<div><h2>A</h2><div><h2>B</h2>test</div></div>

Actual Result:

The shortcode results in

<div><h2>A</h2><div><h2>B</h2></div>test<div><h2>B</h2></div>test</div>[/wporg]

Issue Description

Include examples for the Caddy webserver.

URL of the Page with the Issue

Brute Force Attacks

Sections of Page with the issue

Protect Your Server
Password Protect wp-login.php
Limit Access to wp-login.php by IP
Deny Access to No Referrer Requests

Why is this a problem?

Examples for other webservers will make these sections more useful.

Suggested Fixes

Protect Your Server #

At the end of this section, please add the following...

For Caddy, you can use the error directive to protect your site. In the example below, wp_admin has been locked down.

    # Trigger a 401 error for wp_admin
    error /wp-admin* "Unauthorized" 401

    # Handle the error by serving an HTML page
    handle_errors {
        rewrite * /401.html
        file_server
    }

Password Protect wp-login.php #

At the end of this section, please add the following...

For Caddy, you can password protect your wp-login.php file using the basicauth directive.

    basicauth /wp-login.php {
        # Add separate lines for each additional user
        user1 password-hash1
    }

Caddy configuration does not accept plaintext passwords; you MUST hash them before putting them into the configuration. The caddy hash-password command can help with this.

Limit Access to wp-login.php by IP #

At the end of this section, please add the following...

For Caddy, use the remote_ip request matcher to limit access to wp-login.php by IP address.

    @blacklist {
        # All except the specifed addresses
        not remote_ip forwarded 203.0.113.15 203.0.113.16 203.0.113.17
        # or for the entire network
        # not remote_ip forwarded 203.0.113.0/24
        path /wp-login.php
    }

    # Block access to wp-login.php for blacklisted addresses
    respond @blacklist "Forbidden" 403 {
        close
    }

Deny Access to No Referrer Requests #

At the end of this section, after the IIS example, but before the text...

Change example.com to your domain. If you’re using Multisite with mapped domains, you’ll want to change example.com to (example.com|example.net|example4.com) and so on. If you are using Jetpack comments, don’t forget to add jetpack.wordpress.com as referrer: (example.com|jetpack\.wordpress\com)

please add the following...

For Caddy, mitigate brute force login and spam comment attempts from bots.

    # Mitigate spam attack logins and comments
    @protected path_regexp (wp-comments-posts|wp-login)\.php$
    handle @protected {
        @no-referer {
            not header Referer https://{host}*
            method POST
        }
        abort @no-referer
    }

Using abort for blocking bots is more efficient because Caddy will just drop the connection immediately instead of sending back a response.

Links to relevant resources

1. The suggested text and code was discussed extensively with Caddy core maintainers in this Caddy forum thread Using Caddy to deter brute force attacks in WordPress

Issue Description

This information seems wrong, or at least contradicting to https://wordpress.org/support/article/must-use-plugins/

MU Plugins can by my knowledge be used as well in single installs. It is long time ago that these where multi user plugins, now those are must use plugins.

URL of the Page with the Issue

https://wordpress.org/support/article/managing-plugins/

Section of Page with the issue

https://wordpress.org/support/article/managing-plugins/#must-use-plugins

Why is this a problem?

It is a main landing page of the WordPress help tabs, and holds what seems wrong information.

Suggested Fix

Update the section reflecting that MU Plugins are just that: Must Use Plugins. Not related to MultiUser in any way, at least, not anymore.

Hope I am not wrong on this :)

Issue Description

The Plugin Handbook page describes the table of contents in an ordered list.

1. It appears that the Privacy chapter was added to the table of contents after this page was written. It is missing.
2. Some of the chapter (or "section") numbers mentioned in the list are incorrect.
3. There is inconsistent terminology used: The table of contents list in the left sidebar column is labeled Chapters, while the main content's ordered list refers to "sections".

URL of the Page with the Issue

https://developer.wordpress.org/plugins/

Section of Page with the issue

The main content ordered list

Why is this a problem?

The Privacy chapter is omitted from the list. Readers are given incorrect section numbers compared to what is in the Chapters list in the left hand sidebar. They also might not realize that "sections" are the same as chapters.

All of these issues could be confusing, or could make it slightly harder to find information than it needs to be.

Suggested Fix

After list item number 3, a list item should be added mentioning the Privacy chapter. Beginning with ordered list item number 4, all of the "sections" mentioned should be incremented by 1. "Sections" should be referred to as chapters.

The entire ordered list should read like this (changes are in bold, notes are italicized in parenthesis):

1. If you’re new to plugin development, start by reading the introduction and then move on to the basics.
2. Chapter 3 will introduce you to plugin security.
3. Hooks are what make your plugin interact with WordPress. Learn all about them in chapter 4.
4. You can learn about Privacy best practices in chapter 5. (This is my own wording, but should be changed to whatever makes sense--this was just an example.)
5. To find out more about WordPress’ built-in functionality that you can use in your plugin, check out chapters 6 – 12: administration menus, shortcodes, settings, metadata, custom post types, taxonomies, and users.
6. Learn about getting data using the HTTP API in chapter 13.
7. If you’re using JavaScript, jQuery or Ajax in your plugin, you’ll find the information you need in chapter 14.
8. To learn about time-based WordPress tasks using Cron, check out chapter 15.
9. Chapters 16-18 will introduce you to internationalizing your plugin, preparing it for release on WordPress.org, and some developer tools you might find useful.

Issue Description

This DOC's code example is outdated and suboptimal.
It should be updated to use a more modern approach.
I have already put a newer example on this page.

URL of the Page with the Issue

https://developer.wordpress.org/apis/handbook/quicktags/

Section of Page with the issue

https://developer.wordpress.org/apis/handbook/quicktags/#examples

Why is this a problem?

The first Problem is, the example shows to print a script instead of enqueueing it.
The second Problem is, it does not elaborate on the fact that any script trying to target those QuickTags has to be inside the call-back Function.
See my "More modern example" on the old codex.

Suggested Fix

Add this example along with the existing one (which is not wrong, it is just suboptimal and shouldn't be done like that if possible to avoid).

Source article

Giving WordPress Its Own Directory

The problem I'm having

There are multiple issues with this article. See https://wordpress.org/support/topic/giving-wordpress-its-own-directory-24/.

Suggested improvements

1. Moving a Root install to its own directory
   This section is misleading. What’s impacted is the WordPress Address URL, not the Site Address URL. The site is still accessed at https://example.com. What changes between method I and II is that WordPress is accessed at https://example.com (Method I) or https://example.com/subdir (Method II). Suggested update:

Moving a Root install to its own directory #

Let’s say you’ve installed WordPress at example.com. Now you have two different methods to move WordPress installations into a subdirectory:

1. Without a change in the WordPress URL (remains example.com)

2. With a change in the WordPress URL (it will redirect to example.com/subdirectory)

2. Method II (With URL change)
   Here’s an instance where Google backfires. A search reveals there are many opinions on what constitutes WP core files. The intent of the article is that core means the whole WP installation. I believe the best way to address this is to remove the word ‘core’ from this section.

3. .htaccess modification
   The heading level and the placement of this section suggests that it is related to Method II. In fact, it appears to be more closely aligned to Method I. Suggested update: Move this section before the main section Method II (With URL change). This will make it clearer that it's associated with section Method I (Without URL change)

References

1. Giving WordPress Its Own Directory
2. https://wordpress.org/support/topic/giving-wordpress-its-own-directory-24/

Issue Description

The "Comment Moderation" article references a "blacklist" for comments. The most recent version of WordPress refers to these as "Disallowed Comment Keys".

Additionally, the last section on the page is entitles "Why Not Blacklisting". From my understanding, it appears that the current functionality for the "Disallowed Comment Keys" (as described in this documentation) is exactly the behavior that this section says WordPress does not use.

URL of the Page with the Issue

https://wordpress.org/support/article/comment-moderation/

Section of Page with the issue

The last paragraph of "Controlling Moderation" and the entire "Why Not Blacklisting" section.

Why is this a problem?

This documentation uses terminology that does not reflect what users would see in their admin panel, and may be confusing. The term "blacklist" also has a harmful social history, and should ideally be replaced with a more inclusive alternative. The "Why Not Blacklisting" section also contradicts some of the current features available in WordPress, and could cause users to be confused.

Suggested Fix

I would recommend replacing "blacklist" with "disallowed comment keys" (or something that uses similarly inclusive language). I also think it might be worth re-evaluating whether the "Why Not Blacklisting" section is still pertinent given present admin functionality.

If there is a way for me to contribute these changes directly, please let me know! Thank you 🙌

What is the new page you are requesting?

As mentioned in #30 , some docs is too technical for end users and should be moved to dev docs. At this point we don't know exactly which topics are covered so we're going to use this issue to list all docs that should be migrated so we can decide the place for them. Some are fairly common topics and might need a completely new place (such as .htaccess, Localisation and Internationalisation, Escaping, Sanitising..)

How will this new page help you?

We will have one centralised place for documenting common topics that are not specific for theme or plugin developers. We can link to these pages from HelpHub articles for more advanced and tech savvy users while keeping the end user documentation not confusing for others.

Issue Description

I could not help but notice that often Dashboard and Administration Panel are used interchangeably.
I think it would be better to stick to one - and I think Dashboard is the adequate terms since there is a reference to that in the WP Admin Area, while there is no Administration Panel.

URL of the Page with the Issue

I noticed this here https://wordpress.org/support/article/writing-posts/ but it (most likely) also happens elsewhere.

Section of Page with the issue

See Log in to your WordPress Administration Screen (Dashboard).. Later, only Administration Panel is used, however.

Why is this a problem?

It is not consistent. Specially for a beginner, which is for whom those docs are intended, it is very important to have a reference to things that exist in front of their eyes, so - a Dashboard is clear because there is a link/menu item in the WP Admin Area called Dashboard. But there is no where an Administration Panel.
This could be anything. It could be a single screen, the settings screen, the Dashboard...

Suggested Fix

Agree on one term and use one term only.

Issue Description

In this DOC https://wordpress.org/support/article/posts-screen/, there are several links intended to be anchor links, but they lead to other (irrelevant) pages.

URL of the Page with the Issue

https://wordpress.org/support/article/posts-screen/

Section of Page with the issue

Example:
https://wordpress.org/support/article/posts-screen/#actions > BULK EDIT

Why is this a problem?

There are links that are intended to link back to anchors on the same page.
Clicking those, however leads to pages like https://codex.wordpress.org/#Editing%20Individual%20Posts instead of the actual anchor.

Suggested Fix

Go thru the DOC, check each #anchor link and make sure it points to the correct on-page anchor.
Example in BULK EDIT Section:
selected, Bulk Action, Applied all lead to other pages.
The correct anchors would be (probably):
https://wordpress.org/support/article/posts-screen/#selection
https://wordpress.org/support/article/posts-screen/#actions
etc

Issue Description

Articles Overview of WordPress and History are similar and complimentary of each other.

URL of the Page with the Issue

https://wordpress.org/support/article/overview-of-wordpress/ and https://wordpress.org/support/article/history/

Section of Page with the issue

Title after merging documents.

Why is this a problem?

The intention of both articles is to give the end-user background information about what WP is, its origin and where it is going. Neither article has technical information.

This fix is part of the recategorization project.
For more information reach out to @estelaris on Slack - docs channel.

Suggested Fix

• Merge both articles
• change the title to: Learn about WordPress origins and version history
• Mark old articles as 301-overviews (this still needs discussion with meta team to find out how we are going to do it)

On REST API authentication page https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/ :

While cookie authentication is the only authentication mechanism available natively within WordPress, plugins may be added to support alternative modes of authentication that will work from remote applications. Some example plugins are OAuth 1.0a Server, Application Passwords, and JSON Web Tokens.

1. At this point, also application passwords is available natively, no need for a plugin.

2. "OAuth 1.0a Server" is last updated 5 years ago. Although, it may still be working all right and I don't know if there are better alternatives.

Issue Description

A new title was recommended during GSoD

URL of the Page with the Issue

https://wordpress.org/support/article/new-to-wordpress-where-to-start/

Section of Page with the issue

Title

Why is this a problem?

Title needs to follow the guidelines as written during GSoD

This fix is part of the recategorization project. Our goal is to reorganize the end-user articles in HelpHub in order to make them easier to find and more accessible to the end-user.
Articles will be merged, removed, updated and added to a new category.
For more information reach out to @estelaris on Slack - docs channel.

Suggested Fix

Change title to Get started with WordPress

This issue was moved from HelpHub issue #315 originally reported by ribaricplusplus.

Hello,

I think this server side code is incorrect. It's supposed to be handling the AJAX request, yet it seems to be enqueueing JavaScript.

Issue Description

Breadcrumb overlays the page title on smaller screen when the breadcrumb contains at lest 3 lines.

URL of the Page with the Issue

https://make.wordpress.org/polyglots/handbook/for-editors/translation-collaboration-team-building-tips/guide-organize-a-local-event-on-global-wordpress-translation-day/

Section of Page with the issue

Breadcrumb

Why is this a problem?

It is ugly and makes the breadcrumb and page title poor readability.

Suggested Fix

I checked with my web browser's inspector tool and seems likely we couldn't add media query CSS to fix this issue due to absolute positioning on breadcrumb and the below CSS code presents:

@media only screen and (min-width: 876px) {
    .single-handbook .handbook-breadcrumbs ~ #primary {
        padding-top: 7rem;
    }
}

Probably adding additional breadcrumb element that is shown only on mobile creen and put it inside DIV#primary before the page title part would fix. Don't forget to hide the current .handbook-breadcrumbs on desktop.

Issue Description

When reading https://wordpress.org/support/article/writing-posts/ it appears that many times a phrase similar to For more information, see {Topic}. is used.
But it is never linked to any further reading topic, thus the user/reader has actually to google the subject. Often there are actually additional docs we could link to in here.

URL of the Page with the Issue

https://wordpress.org/support/article/writing-posts/

Section of Page with the issue

• Excerpt
• Send Trackbacks
• Post Author

Why is this a problem?

It is not a huge problem but it is kinda pointless saying something like For more information, see Users and Authors. and then not linking to anything talking about it. If I google that, I could possibly find any sort of information Users and Authors, not just WP related.

Suggested Fix

Either remove all those references or link to the particular relevant DOC, as shown below:

• Excerpt. => https://wordpress.org/support/article/excerpt/
• Send Trackbacks => ?
• Post Author => https://wordpress.org/support/article/roles-and-capabilities/ (?)

Source article

Using Permalinks

The problem I'm having

The WordPress article Using Permalinks has the one and only reference in WordPress support docs to Caddy. However, the reference is for Caddy V1, which is now defunct. Caddy V2 has been out since May 2020.

Suggested improvements

1. Under the section mod_rewrite: “Pretty Permalinks”, alter the bullet point...

• Caddy using rewrite, e.g. according to this tutorial

...to instead read...

• Caddy automatically in a default WordPress installation. This is the default built-in behaviour of the php_fastcgi directive.

2. Under the section Using “Pretty” permalinks, add the following bullet point:

• For Caddy, a web server that supports HTTPS natively, the rewrite rule may need to be adjusted if WordPress files are moved to a subdirectory. Refer to Using Caddy to give WordPress its own directory for details.

The suggested text improvements were discussed in this Caddy forum thread WordPress: Using Permalinks

References

1. Using Permalinks
2. WordPress: Using Permalinks

Source article

Giving WordPress Its Own Directory

The problem I'm having

The article is Apache-centric and doesn't support other webservers. It's an important article as it's referenced from the WP General Settings screen.

Suggested Improvement

Please include a reference to an equivalent article for the Caddy webserver e.g.

See Also #

1. Using Caddy to give WordPress its own directory

References

1. Giving WordPress Its Own Directory
2. Using Caddy to give WordPress its own directory

Issue Description

I found broken links at two articles.

URL of the Page with the Issue

1. https://make.wordpress.org/support/handbook/giving-good-support/examples-of-good-vs-bad-support/
2. https://make.wordpress.org/support/handbook/giving-good-support/understanding-users-reading-beyond-the-question-and-probing/

Section of Page with the issue

1. Broken link is at: "As covered in Approach to providing good support and"
2. Broken link is at: "It’s easy to leave a bad reply,"

Why is this a problem?

The links go to a non-existing page which prevents people from learning, an it's also confusing.

What is the new page you are requesting?

In the Plugin Developer Handbook, we have a section Developer Tools, which outlines using two WordPress Plugins. I want to add a page, describing the usage of wpcs with the WordPress-Extra sniff rules so that a plugin developer can be made aware of possible security related issues. These issues do come up during the first submission of a plugin, and could be immensely helpful for both the plugin developer and the reviewer.

How will this new page help you?

In the #pluginreview channel, we were having some discussions using wpcs, especially the WordPress-Extra sniff rules to detect and prevent potential security (sanitization, validation and escaping) issues while developing a plugin. Personally, I feel, if I knew this prior to submitting my plugin to the repository, it would’ve saved both the reviewer and me, some valuable time. I had read the guides on Plugin Security available on plugin developer’s handbook, but definitely knowing that the WordPress-Extra sniff exists to automatically detect many of such issues is very helpful.

So I would like to contribute to the plugin developer handbook outlining setting up wpcs with the sane defaults as explained in the wpcs repository. I would like to explain both the cli setup and editor setup, with some examples and screenshots. Previously I had contributed to the (now archived) eslint config wordpress repository, so I have some experience writing documentation for WordPress related dev-tools.

Please let me know how to proceed. These are the rough outline of the documentation I have in mind.

• What is PHPCS and WPCS - Explain in brief the purpose of the sniffing/linting tools and how wpcs extends PHPCS with WordPress specific rules.
• Setting up PHPCS through CLI - Preferable with composer (devDepencency), also installing WPCS. Linking to the GitHub wiki page for detailed instructions.
  • Setup a sniffing rule for the Plugin - Creating a phpcs.xml file with a default config.
  • Running phpcs through CLI - Running the command and creating a composer script.
  • Gradual Adoption of Sniffing Rules - How to disable rules not relevant to the project (like style rules, which aren't applicable to a plugin). What rules to never disable (related to sanitization, escape, validation etc).
• Setting up PHPCS/WPCS in your IDE - Quick overview of setting it up in VSCode. Link to the wiki page for additional editors.

This issue was originally created as HelpHub #333 by atachibana and comment was added by ashfame.

There are two methods:

1. Using the plugin
2. Setting up WordPress manually (without plugin)

For above method 2, the step will be (but might be missing)

1. Backup WordPress files and database
2. Set SSL certificate
3. Change WordPress URL from Administration Screen
4. Replace the string 'http' to 'https' in the database contents
5. Add redirect code into .htaccess

Comment by ashfame

I just switched an old site to refresh up my memory for the exact steps:

Actual Instructions

• Take a backup of files and database in case you need to revert for whatever reasons.
• Get your webhost to install a TLS (also referred to as SSL) certificate for your website
• Once installed ensure that your website is accessible on https URL, by simply replacing http with https i.e. adding a s to it. Eg: If your website was http://www.domain.com, new URL would be https://www.domain.com
• See if you have any errors in your browser console complaining about mixed content, as you browse different pages on your website. Usually when using good quality plugin and theme, there won't be an issue. But if you do, you will need to resolve these issues.
• Once you are satisfied with the results and are ready to flip the switch, go ahead and update the website URL in WordPress admin: Settings > General.
• Now if you try to access http version of your website you will be redirected to https version. Best to try in an incognito/private window in your browser to test this.

Potential issues:

http to https redirect isn't working

I am not sure if changing the URL in WordPress causes it to issue redirects, though I believe it does. I never use it, as I always handle redirects on a server level.

Mixed-content warnings

Depending on what resources are causing these errors, it can either be your theme, any plugin you use or actual content you load in post/page and requires a different approach for each one of them.

Post/page content requires you to replace string, can be done via this plugin https://wordpress.org/plugins/better-search-replace/

Theme/plugins would require using the right functions to generate URLs or simply update the hardcoded urls to be https.

The overall design needs updating and modernizing to work better in a multi-device, responsive world. The fonts and typography are quite small and difficult to read. The middle columns are narrow, the sidebars are cramped and the overall look and feel of the documentation sites look dated.

This cuts across the entire Make network of sites, and the News site has a design refresh in the works. Ideally we can poach styles from those updates and improve the documentation sites.

Issue Description

There is a typo in the link destination.

URL of the Page with the Issue

https://developer.wordpress.org/plugins/taxonomies/working-with-custom-taxonomies/

Section of Page with the issue

Introduction to Taxonomies

Why is this a problem?

Currently in the introduction to taxonomies section, there is a link to taxonomies page. But the link returns page not found.

Suggested Fix

https://developer.wordpress.org/plugins/taxonomy/ should be replaced by https://developer.wordpress.org/plugins/taxonomies/

Issue Description

A new title was recommended during GSoD

URL of the Page with the Issue

https://wordpress.org/support/article/wordpress-features

Section of Page with the issue

Title

Why is this a problem?

Title needs to follow the guidelines as written during GSoD

This fix is part of the recategorization project. Our goal is to reorganize the end-user articles in HelpHub in order to make them easier to find and more accessible to the end-user.
Articles will be merged, removed, updated and added to a new category.
For more information reach out to @estelaris on Slack - docs channel.

Suggested Fix

Change title to Learn about WordPress features

The example code of code reply script (https://developer.wordpress.org/themes/basics/including-css-javascript/#the-comment-reply-script) is broken:

if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
    wp_enqueue_script( 'comment-reply' );
}

And the example code in the next section ("Combining Enqueue Functions") as well.

Issue Description

I’ve come across support replies telling them users to „add this code to XY file: {code here}“

no explanation as of what the code does or why it’d be useful.

this is generally a bad idea IMO and shouldn’t be done.

thus I’d suggest adding a section to https://make.wordpress.org/support/handbook/giving-good-support/ mentioning to please elaborate on an answer so it is clear what the instructions mean and should accomplish.

URL of the Page with the Issue

https://make.wordpress.org/support/handbook/giving-good-support/

Section of Page with the issue

Requires new section

Why is this a problem?

The worst support are instructions that aren’t explained, the point of good support is the user afterwards is richer in knowledge and doesn’t just have a copy paste solution that maybe or maybe not magically works (or exploits his site?)

Suggested Fix

When giving support, explain why your answer will help and how it will resolve the issue

examples of bad answer:

Add this to wp-config: code here

Or

Add below line to your wp-config.php before /* That’s all, stop editing!…*/
define(‘COOKIE_DOMAIN’, $_SERVER[‘HTTP_HOST’] );

Better:

due to xy it might be that (issue) happens.
a possible solution is to do (task)
this might resolve the Problem because (reason)
take these precautions first (list)

On page https://developer.wordpress.org/themes/basics/the-loop/ , the last two headers seem to have some duplication in them (repeating the function name twice).

On https://developer.wordpress.org/rest-api/using-the-rest-api/client-libraries/ , there are client library recommendations for JavaScript, Ruby, C#.

I would suggest adding a recommendation for PHP as well, seeing as how Wordpress is run by PHP itself.

This could be a good enough candidate: https://github.com/varsitynewsnetwork/wordpress-rest-api-client (last updated 10 months ago).
This one probably not so: https://github.com/WP-API/client-php (last update 7 years ago).

BTW, the recommended Ruby one is unmaintained too, tested up to WP 4.7.2, last updated 4 years ago.

Issue Description

We want to keep an eye on all contributors to Docs team so we have a document CONTRIBUTORS.md. Everyone who reported issue, fixed issue and/or participated in discussion should create PR to add their info in this document. Required info is wp.org username, GitHub username and GitHub issue number.

URL of the Page with the Issue

https://github.com/WordPress/Documentation-Issue-Tracker/blob/main/README.md

Section of Page with the issue

Getting Recognition - https://github.com/WordPress/Documentation-Issue-Tracker/blob/main/README.md#getting-recognition

Why is this a problem?

This section is mentioning Google Docs but that's just unnecessary dispersing over more tools when we have everything we need here. Plus, having issue numbers gives more insight in which part of docs contributors were involved and therefore, provide more context.

Suggested Fix

Replace Google docs info with GitHub PR from the description above.

Issue Description

In the following remarks:

callbacks bound to it can accept none (the same as 1) of the arguments or up to four

If no arguments were accepted by the callback that is considered to be the same as accepting 1 argument.

Accepting zero/one arguments.

It is not precisely clear what it means for none/no/zero arguments to be "the same as 1" argument.

If it means that functions with 0 arguments may be used as callbacks for filters with 1 argument, it is true for filters with 2, 3, and 4 arguments as well. E.g., this does work all right:

function test_callback () {
  return true;
}
add_filter('http_request_host_is_external', 'test_callback', 7, 0);
add_filter('http_request_host_is_external', 'test_callback', 8, 1);
add_filter('http_request_host_is_external', 'test_callback', 9, 3);

If it means that functions with 1 argument may be used as callbacks for filters with 0 arguments, it is not true. E.g., this :

function test_callback ($allow) {
 error_log('Worked' . $allow);
 return false;
}
add_filter('http_request_host_is_external', 'test_callback', 7, 0);

produces error
Too few arguments to function test_callback(), 0 passed [..] and exactly 1 expected

If it means that there is no difference whether you add filter with $accepted_args = 0 or $accepted_args = 1, it is not true either:

function test_callback ($allow = null) {
  error_log(var_export(['$allow' => $allow], true));
  return false;
}
add_filter('http_request_host_is_external', 'Lvlv_auth\test_callback', 7, 1);
add_filter('http_request_host_is_external', 'Lvlv_auth\test_callback', 8, 0);

produces output (the value is not the same):

 array (
  '$allow' => false,
)
array (
  '$allow' => NULL,
)

URL of the Page with the Issue

https://developer.wordpress.org/reference/functions/add_filter/

Section of Page with the issue

Description

Why is this a problem?

The remark about zero arguments is ambiguous and/or unclear and/or unnecessary.

Suggested Fix

One option would be to just delete the remarks about 0 arguments being the same as 1 argument.
Or if not then reword the remark somehow, but I have no suggestion for that as it's not clear to me what is meant.

Issue Description

Only Apache examples are provided,

URL of the Page with the Issue

Hardening WordPress

Sections of the Page with the issue

Securing wp-includes
Securing wp-config.php

Why is this a problem?

Examples for other webservers will make these sections more useful.

Suggested Fixes

Immediately after the text...

Securing wp-includes #

A second layer of protection can be added where scripts are generally not intended to be accessed by any user. One way to do that is to block those scripts using mod_rewrite in the .htaccess file. Note: to ensure the code below is not overwritten by WordPress, place it outside the # BEGIN WordPress and # END WordPress tags in the .htaccess file. WordPress can overwrite anything between these tags.

# Block the include-only files. 
<IfModule mod_rewrite.c> 
RewriteEngine On 
RewriteBase / 
RewriteRule ^wp-admin/includes/ - [F,L] 
RewriteRule !^wp-includes/ - [S=3] 
RewriteRule ^wp-includes/[^/]+\.php$ - [F,L] 
RewriteRule ^wp-includes/js/tinymce/langs/.+\.php - [F,L] 
RewriteRule ^wp-includes/theme-compat/ - [F,L] 
</IfModule> 

# BEGIN WordPress

Note that this won’t work well on Multisite, as RewriteRule ^wp-includes/[^/]+\.php$ - [F,L] would prevent the ms-files.php file from generating images. Omitting that line will allow the code to work, but offers less security.

... add in the following text...

For a Caddy web server, use a named matcher set to secure the include paths while still allowing access to ms-files.php for multisite.

    @forbidden {
        not path /wp-includes/ms-files.php
        path /wp-admin/includes*
        path /wp-includes*
    }
    respond @forbidden "Access denied" 403

... and immediately after the text...

Securing wp-config.php #

You can move the wp-config.php file to the directory above your WordPress install. This means for a site installed in the root of your webspace, you can store wp-config.php outside the web-root folder.

Note: Some people assert that moving wp-config.php has minimal security benefits and, if not done carefully, may actually introduce serious vulnerabilities. Others disagree.

Note that wp-config.php can be stored ONE directory level above the WordPress (where wp-includes resides) installation. Also, make sure that only you (and the web server) can read this file (it generally means a 400 or 440 permission).

If you use a server with .htaccess, you can put this in that file (at the very top) to deny access to anyone surfing for it:

<files wp-config.php> 
order allow,deny 
deny from all 
</files>

... add in the following text...

For a Caddy web server, add the wp-config.php path to the named matcher set described under Securing wp-includes. This will prevent access to wp-config.php in the webroot,

        path /wp-config.php

Links to relevant resources

1. The suggested text and code was discussed extensively with Caddy core maintainers in this Caddy forum thread Using Caddy to harden WordPress.

Issue Description

• In the introduction to the Glossary it says "If you are a contributor please don’t add definitions for generic terms (API, PHP, JavaScript, etc…).". But there are glossary entries for all these terms.
• https://wordpress.org/support/article/glossary/#bookmarklet - 'their' would be more gender-inclusive than 'his/her'.
• https://wordpress.org/support/article/glossary/#cvs - typo, "‘used to be used coordinate WordPress development." should instead be "‘used to be used to coordinate WordPress development.’.
• https://wordpress.org/support/article/glossary/#blog - this definition is maybe a bit outdated as it is more common for corporations to use blogs now
• https://wordpress.org/support/article/glossary/#moblogging - I'm not sure how many people understand this pronunciation transcription system (I don't).
• https://wordpress.org/support/article/glossary/#quicktag - I think the 'Back to the top' link shouldn't be here but at the very bottom of the page
• https://wordpress.org/support/article/glossary/#rdf would be nice if ‘RSS’ hyperlinked to the glossary entry for RSS
• https://wordpress.org/support/article/glossary/#unicode - “The most widely used collections of these character sets are the iso-8859 with iso-8859-1 and iso-8859-15 (which contains the euro sign and some characters used in Dutch, French, Czech and Slovak)“ -> I’m not sure why those languages specifically are named, it sounds a bit strange. According to the Wikipedia page, there are characters from more languages in iso-8859-15

URL of the Page with the Issue

https://wordpress.org/support/article/glossary/

Section of Page with the issue

Why is this a problem?

Suggested Fix

Issue Description

Only an Apache example is provided.

URL of the Page with the Issue

HTTPS for WordPress

Section of Page with the issue

Best Practices for HTTPS for WordPress

Why is this a problem?

Examples for other webservers will make this section more useful.

Suggested Fix

Immediately after the text...

It is recommended for all production WordPress sites to use HTTPS.

Use a reputable web host, most provide HTTPS service as a standard.
Use a SSL Certificate from Let’s Encrypt, they are free and easy to use.
Serve Static Content from an SSL enabled CDN
You may need to redirect your HTTP traffic to your HTTPS site. For Apache, you can do so by creating two VirtualHost entries for example:

<VirtualHost *:80>
    ServerName mkaz.blog
    Redirect / https://mkaz.blog/
</VirtualHost>

<VirtualHost *:443>
    ServerName mkaz.blog
    DocumentRoot /home/mkaz/sites/mkaz.blog
    <Directory /home/mkaz/sites/mkaz.blog>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/mkaz.blog/cert.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/mkaz.blog/privkey.pem
    SSLCertificateChainFile /etc/letsencrypt/live/mkaz.blog/fullchain.pem
    IncludeOptional /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>

Please add the following example for the Caddy webserver.

The Caddy web server activates HTTPS by default for qualifying domain names and automatically enables HTTP → HTTPS redirects. By default, it obtains certificates from Let’s Encrypt and renews them automatically.

example.com { 
    # Set this path to your site's directory:
    root * /var/www/html

    # Enable Gzip compression:
    encode gzip

    # Serve WordPress PHP files through php-fpm:
    php_fastcgi unix//run/php/php7.4-fpm.sock

    # Enable the static file server:
    file_server
}

✍️ Depending on your PHP-FPM config, the php_fastcgi can also be php_fastcgi 127.0.0.1:9000.

Links to relevant resources

1. The suggested text and code was discussed extensively with Caddy core maintainers in this Caddy forum thread HTTPS for WordPress using Caddy

Issue Description

Content update

URL of the Page with the Issue

https://wordpress.org/support/article/new-to-wordpress-where-to-start/

Section of Page with the issue

These changes are in section Step four – Set up WordPress

Why is this a problem?

Excesive and unnecesary linking

Suggested Fix

• Step four | For help on creating ... Users > Your Profile pages for guidance. Remove the link to Users.
• Step four | To set the site name and other information ... go to Administration > Settings > General. Administration, Settings and General are linked to different pages, and while that is great, neither Administration nor Settings explain how to add/change the name site. Remove both links. Also, add ""in the dashoboard"" at the end of the sentence.
• Step four | After you have published ... quick edit features in the Administration > Posts > Posts screen. Administration and posts (the first one) links are not needed.
• Step four | Add your About ... information Pages by going to Administration > Pages > Add New. Remove the link to Administration.
• Want to change the ... site? Go to Administration > Appearance > Themes. Remove the links to Administration and Appearance.

WordPress speed complaints have long been a thorn in our side. We have been analyzing some complex WordPress sites we host and one aspect which weighs heavily on the php consumption is the use of init and admin_init hooks in plugins. The reason this appears to compound php loads is due to plugins which commonly use AJAX. This often leads to a large volume of init/admin_init calls running repeatedly and rapidly. The WordPress "heartbeat" is a common culprit but many Page Builders are just as likely to lead to the same issue.

The reason repeated calls to admin_init and init hooks lead to PHP spikes is often due to them being incredibly popular hooks to initiate countless plugins in varying degrees. This can especially become a serious bottleneck when a plugin is kicking off a call to an outside API where some sort of remote call such as a curl is being waited on.

We combed through your documentation but could not seem to locate any recommendations to use the function wp_doing_ajax to help alleviate this issue. Obviously every plugin developer would need to stop and consider the implications for using wp_doing_ajax, but I would imagine 90%+ of the plugin use cases could wrap their init/admin_init scripts with if( !wp_doing_ajax ) and see speed improvements.

I hope this perspective is helpful to you and you'll recognize the importance of spreading the word to the WordPress scene about taking advantage of it for the greater good.

Thanks for all you do!

Issue Description

The post type of "Get a faster, more secure website: update your PHP today" isn’t correct

URL of the Page with the Issue

https://wordpress.org/support/update-php/

Section of Page with the issue

All the content

Why is this a problem?

This documentation content is not a post, but a page. Without knowing its url, we can't access this content. There is no menu item to access it, nor a search on /wordpress.org/support/ with the full title for the search terms.

Suggested Fix

Move the content of this page in a documentation post, and add categories.

Issue Description

Update links. Links are to ther WP documentation articles.

URL of the Page with the Issue

https://wordpress.org/support/article/wordpress-features

Section of Page with the issue

Several, in the list below,
example

• the section is listed first | then the sentence with the wrong link and lastly, the correct link

Why is this a problem?

Links still linking to Codex and some are outdated.

Suggested Fix

• Built for publishing: subscribe to specific content sub-feeds link to https://wordpress.org/support/article/wordpress-feeds/
• Backed by community support | vibrant community of users link to https://wordpress.org/support/article/contributing-to-wordpress/
• Backed by community support | Version 4.9 change to the latest version and link to https://wordpress.org/download/counter/
• Beyond black and white | media browser to help you store, organize and find the files link to https://wordpress.org/support/article/media-add-new-screen/
• Never lose a word | automatically saves your work link to https://wordpress.org/support/article/revisions/#autosaves and WordPress creates a snapshot link to https://wordpress.org/support/article/revisions
• Typography nerds rejoice | WordPress silently typesets each and every letter for seamless web production link to https://wordpress.org/support/article/how-wordpress-processes-post-content/
• Drag and drop administration | dynamic functionality on each page link to https://wordpress.org/support/article/appearance-widgets-screen/
• Multiple personalities | define different roles for different users link to https://wordpress.org/support/article/roles-and-capabilities/
• Template driven design | Template tags link to https://developer.wordpress.org/themes/basics/template-tags
• Your site is your castle | sanitizes all user input link to https://developer.wordpress.org/plugins/security/data-validation/
• Maintenace so simple... | one click updates link to https://wordpress.org/support/article/dashboard-updates-screen/