Grav on tilde

To get started with my tilde.club account, I figured a micro blogging cms (content management system) would do nicely. My preliminary searches suggested Grav. However, the installation did not go smoothly, so here are some quick notes to successfully install it.

Manual Install

Due to apparent restrictions on the server, the automated install scripts will fail. It is best to manually install from zip files. Also install plugins and themes this way.

Permissions

Permissions need to be fixed to escape error code 500. The script below will help with that. It also helps privatize files and folders that don't need world access. Run it from ~/public_html.

#!/bin/sh
# Extended grav permissions script
# author: bazz1tv <bazz@bazz1.com>
#
# - fixes perms to escape error 500
# - privatizes files as much as possible
#
# run from ~/public_html
#
# Don't forget to add umask 0007 to index.php after the `namespace Grav;` line
# to force php-user to write files with group-write permissions and world no-perms
# otherwise we won't be able to delete their files without root access.

chown -R $USER:club .
find . -type f -exec chmod 664 {} \;
find ./bin -type f -exec chmod 775 {} \;
find . -type d -exec chmod 775 {} \;
find . -type d -exec chmod +s {} \;

# Bazz Additions
# ensure php-user is able to writes files to cache/
chmod g+w cache

# privatize system/ files except for assets/ and images/
cd system
find . -maxdepth 1 ! \( -path . -o -path ./assets -o -path ./images \) \
  | xargs chmod -R o-rx
cd ..

# recursively privatize directories that can handle it
chmod -R o-r user/config/ user/pages/ vendor/

# privatize root directory files
chmod o-r *.md *.json composer.*

# hide all directories from browser index
find . -type d ! -path . | xargs chmod o-r

Th patch below enables php-user to write files with group-write enabled. If you don't do this, there will be files created in cache/ that you can't delete. It also disables world rwx perms for privacy/security.

--- index.php   2024-03-18 13:36:25.000000000 -0400
+++ index.php.new   2024-05-08 20:20:06.580180873 -0400
@@ -8,6 +8,7 @@
  */

 namespace Grav;
+umask(0007);

 \define('GRAV_REQUEST_TIME', microtime(true));
 \define('GRAV_PHP_MIN', '7.3.6');

Page Routing

The home page is the only one that works out of the box here. When you try to click another page's link (typography) you will get a 404 error code. For example, typography's link refers to ~YOURNAME/typography, a non-existent file. tilde.club does not support URI paths that aren't an actual file. I've come up with a way around this.

• add to user/config/system.yaml: custom_base_url: 'https://tilde.club/~YOURNAME'

Next we'll get the typography page to work correctly.

1. In user/pages/02.typography/, edit default.md and add slug: typography.php to the header (---)
2. from the public_html folder, create a symlink to index.php with the slug name:
   ln -s index.php typography.php

You will do a similar sequence of steps when creating new pages.

With that, it is now working :)

Images

You can put images directly in the page folder. It can be referenced from the markdown or html like:

![markdown relative path](image.png "My Image")
![markdown absolute path](/user/pages/02.typography/image.png "My Image")

<img alt="abs path" src="/~YOURNAME/user/pages/02.typography/image.png" title="My Image"/>

for markdown tags, relative paths are based from the directory the markdown file is located. Absolute paths are based from the custom_base_url

for html tags, all paths are based from / aka http://tilde.club/

For graphics whose scope is outside a single blog post, consider creating a user/images directory. Images there would be addressed in the same exact way (relatively from the markdown file's location or absolutely as explained)

Drafting

When you want to develop your markdown while previewing it over the website, privately. Add visible:false to the markdown file's header section. Make sure you've done the slug symlinking as previously discussed. Then, you can visit the url of your post manually, and it won't be listed in your blog.

Shortcomings

The big pitfall of running grab on tilde.club is that you can't have a subsection of articles, or nested articles. :( This again has to do with the playing around with naming of endpoints with the php extension.

Related Files

These are files and functions that led me to the routing solution

 - system/src/Grav/Common/Page/Page.php
  - url()
 - system/src/Grav/Common/Uri.php
  - rootUrl()
  - init()