picocms / Pico

Pico is a stupidly simple, blazing fast, flat file CMS.
http://picocms.org/
MIT License
3.84k stars 614 forks source link

Documentation improvement proposal on URL-Rewrite for Apache, allow .htaccess #435

Closed loloyd closed 6 years ago

loloyd commented 6 years ago

Please excuse me for my being a novice in GitHub, PicoCMS and the open-source scene in general but I would like to propose a very little improvement on the documentation regarding the URL-Rewrite feature, especially for self-hosted or locally hosted installations with Apache. Currently, there's no mention of specifying that .htaccess should be enabled. I propose that this specification be included in the documentation for completeness. This is related to version 1.0.6 but may also relate to other versions that did not mention this specification.

For self-installed Apache installations, the option "AllowOverride All" enables .htaccess per-directory overrides in the appropriate Apache conf file. Example taken from https://www.linode.com/docs/web-servers/apache/how-to-set-up-htaccess-on-apache/

File: /etc/apache2/sites-available/example.com.conf Config snippet:

<Directory /var/www/html/example.com/public_html>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

The following resources may need to be updated regarding this proposal:

The following change is therefore proposed:

From:

If you're using the Apache web server, URL rewriting probably already is
enabled - try it yourself, click on the [second URL](%base_url%/sub/page). If
you get an error message from your web server, please make sure to enable the
[`mod_rewrite` module][ModRewrite]. Assuming the second URL works, but Pico
still shows no rewritten URLs, force URL rewriting by setting
`$config['rewrite_url'] = true;` in your `config/config.php`.

To:

If you're using the Apache web server, URL rewriting probably already is
enabled - try it yourself, click on the [second URL](%base_url%/sub/page). If
you get an error message from your web server, please make sure to enable the
[`mod_rewrite` module][ModRewrite] and ensure that .htaccess overrides are
enabled ("AllowOverride All" as an appropriate Directory section option).
Assuming the second URL works, but Pico still shows no rewritten URLs,
force URL rewriting by setting `$config['rewrite_url'] = true;` in your
`config/config.php`.

You can probably do better than what I proposed here. Thank you for your consideration.

PhrozenByte commented 6 years ago

Good point, thank you for bringing this up! :+1: Fixed in https://github.com/picocms/picocms.github.io/commit/f5bed1b6eb01b2dcfd43a630587e8571865d76c0 (the docs will be synced later), the changes will go live together with Pico 2.0 (hopefully this or next weekend).