diff --git a/app/routes/guides.py b/app/routes/guides.py index 515d7ab..56097d3 100644 --- a/app/routes/guides.py +++ b/app/routes/guides.py @@ -1,11 +1,109 @@ -from flask import Blueprint, render_template +from flask import Blueprint, render_template, render_template_string, current_app, abort +from pathlib import Path +import re bp = Blueprint('guides', __name__, url_prefix='/guides/') +def parse_guide_title(content: str): + lines = content.strip().split('\n', 1) + fline = lines[0].strip() + if fline.startswith('#'): + title = fline[2:].strip() + content = lines[1] if len(lines) > 1 else '' + return title, content.strip() + + return None, content.strip() + + +def get_guides_by_category(): + guides_dir = Path(current_app.root_path) / 'templates' / 'guides' + categories = {} + + for item in guides_dir.iterdir(): + if item.is_dir() and not item.name.startswith('_'): + category = item.name + categories[category] = [] + for guide_file in sorted(item.glob('*.html')): + if guide_file.name.startswith('_'): + continue + + m = re.match(r'(\d+)-(.+)\.html', guide_file.name) + if not m: + continue + + sort_num = int(m.group(1)) + slug = m.group(2) + + try: + with open(guide_file, 'r') as f: + content = f.read() + + title, template = parse_guide_title(content) + if not title: + title = slug.replace('-', ' ').title() + + categories[category].append(({ + 'sort': sort_num, + 'slug': slug, + 'filename': guide_file.name, + 'title': title, + 'path': f'{category}/{guide_file.name}', + 'url': f'/guides/{category}/{slug}', + 'template': template, + })) + except Exception as e: + current_app.logger.warning(f'failed to read {guide_file}: {e}') + continue + + categories[category].sort(key=lambda x: x['sort']) + + return categories + + @bp.get('/babycode') def babycode(): - return render_template('guides/babycode.html') + # print(get_guides_by_category()) + return '

no

' + + +@bp.get('//') +def guide_page(category, slug): + categories = get_guides_by_category() + if category not in categories: + abort(404) + return + + for i, guide in enumerate(categories[category]): + if guide['slug'] != slug: + continue + + next_guide = None + prev_guide = None + if i != 0: + prev_guide = categories[category][i - 1] + + if i + 1 < len(categories[category]): + next_guide = categories[category][i + 1] + + return render_template_string(guide['template'], next_guide=next_guide, prev_guide=prev_guide, category=category, guide=guide) + + abort(404) + + +@bp.get('//') +def category_index(category): + categories = get_guides_by_category() + if category not in categories: + abort(404) + return + + return render_template('guides/category_index.html', category=category, pages=categories[category]) + + +@bp.get('/') +def guides_index(): + return render_template('guides/guides_index.html', categories=get_guides_by_category()) @bp.get('/contact') diff --git a/app/templates/common/footer.html b/app/templates/common/footer.html index aa81040..be09725 100644 --- a/app/templates/common/footer.html +++ b/app/templates/common/footer.html @@ -2,5 +2,6 @@ Pyrom commit {{ __commit[:8] }} diff --git a/app/templates/common/macros.html b/app/templates/common/macros.html index 644460a..d792974 100644 --- a/app/templates/common/macros.html +++ b/app/templates/common/macros.html @@ -99,7 +99,7 @@ - babycode guide + babycode guide {% if banned_tags %}
Forbidden tags:
@@ -296,6 +296,7 @@

Table of contents

+ (top) {% set toc = sections | extract_h2 %}
    {% for heading in toc %} diff --git a/app/templates/guides/_layout.html b/app/templates/guides/_layout.html new file mode 100644 index 0000000..da41b95 --- /dev/null +++ b/app/templates/guides/_layout.html @@ -0,0 +1,21 @@ +{% extends 'base.html' %} +{% from 'common/macros.html' import guide_sections with context %} +{% block title %}guide - {{ guide.title }}{% endblock %} +{% block content %} +
    +

    Guide: {{ guide.title }}

    + +
    +{% call() guide_sections() %} + {% block guide_content %} + {% endblock %} +{% endcall %} +{% endblock %} diff --git a/app/templates/guides/category_index.html b/app/templates/guides/category_index.html new file mode 100644 index 0000000..38bd047 --- /dev/null +++ b/app/templates/guides/category_index.html @@ -0,0 +1,15 @@ +{% extends 'base.html' %} +{% block title %}guides - {{ category | title }}{% endblock %} +{% block content %} +
    +

    All guides in category "{{ category | replace('-', ' ') | title }}"

    + + +
    +{% endblock %} diff --git a/app/templates/guides/guides_index.html b/app/templates/guides/guides_index.html new file mode 100644 index 0000000..a4f316e --- /dev/null +++ b/app/templates/guides/guides_index.html @@ -0,0 +1,19 @@ +{% extends 'base.html' %} +{% block title %}guides{% endblock %} +{% block content %} +
    +

    Guides index

    + +
    +{% endblock %} diff --git a/app/templates/guides/user-guides/01-introduction.html b/app/templates/guides/user-guides/01-introduction.html new file mode 100644 index 0000000..f5ff4a6 --- /dev/null +++ b/app/templates/guides/user-guides/01-introduction.html @@ -0,0 +1,76 @@ +# Introduction +{% extends 'guides/_layout.html' %} +{% block guide_content %} +
    +

    What is {{config.SITE_NAME}}?

    + {% if config.GUIDE_DESCRIPTION %} +
    {{ config.GUIDE_DESCRIPTION | babycode_strict | safe }}
    + {% endif %} +

    {{ config.SITE_NAME }} is powered by Pyrom, a home-grown forum software for the indie web. This guide will help you get started, from creating an account to understanding how discussions are organized.

    +
    +
    +

    Signing up

    +

    Most interactive features on {{ config.SITE_NAME }} such as creating threads or posting replies require a user account. While browsing is open to all, you must be signed in to participate.

    + {% if config.DISABLE_SIGNUP %} +

    {{ config.SITE_NAME }} uses an invite-only sign-up system. You cannot sign up directly. Instead, {% if config.USERS_CAN_INVITE %}an existing user{% elif config.MODS_CAN_INVITE %}a moderator{% endif %} can generate an invite link containing an invite key. Using that link will take you to the sign up page.

    + {% else %} +

    You can create an account on the sign-up page. After you create your account, a moderator will need to manually approve your account before you can post. This may take some time.

    + {% endif %} +

    To create an account, you will need to provide:

    +
      +
    • A username: +
        +
      • Your username must be 3-20 characters long and only include lowercase letters (a-z), numbers (0-9), hyphens (-) and underscores (_).
        • +
      • If your username includes uppercase characters, the system will automatically convert them to lowercase. Your original capitalization will be preserved as part of your display name.
        • +
      +
      • +
    • A strong password: +
        +
      • Your password must be at least 10 characters long and include at least one uppercase letter, at least one lowercase letter, at least one number, at least one special character, and no spaces.
        • +
      +
      • +
    +

    Once your account is {% if not config.DISABLE_SIGNUP %}confirmed and{% endif %} active, you will have full access to create threads, post replies, and use other features.

    +
    +
    +

    Topics

    +

    The front page of {{ config.SITE_NAME }} is an overview of topics that you can create threads in. A topic is a broad category created by moderators to organize discussions.

    +

    Topics usually have a description that is shown under its name. Use it as guidance for where to post a thread. The order topics show up in is chosen by moderators.

    +

    A topic may be locked by a moderator. This will prevent threads from being created or moved into it by non-moderators. These topics are usually used for forum-wide information, but it is of course up to the moderators.

    +

    By default, threads in a topic are sorted by activity, but this can be changed in your user settings.

    +
    +
    +

    Threads

    +

    Threads are where discussion happens. A thread is started by a user with a name and an initial post, and other users may add their own posts to it (known as replying to the thread).

    +

    When drafting a thread, you have to choose which topic to post it under. Be sure to follow the posting rules. If you created a thread under the wrong topic, you may move it when viewing replies. Moderators have the option to move any thread.

    +

    A thread may be locked by the original poster (OP) or a moderator. When a thread is locked, nobody except moderators can reply to it.

    +

    A thread may also be stickied by a moderator. Stickied threads show above all other threads in the topic it's under. If a thread is stickied, it is likely important.

    +

    You can subscribe to any thread. When subscribed, you will receive an overview of posts you missed for that thread in your inbox.

    +

    You can

    +
    +
    +

    Posts

    +

    Posts are the individual messages that make up a thread. The first post starts the thread, and every subsequent message is a post in reply.

    +

    A post is split up into five sections:

    +
      +
    1. Usercard +
      • The post author's information shows up to the left of the post. This includes their avatar, display name, mention, and status.
      +
      2. +
    2. Post actions +
      • This shows the time and date when the post has been made (or edited), and buttons for actions you can perform on the post, such as quoting or editing.
      +
      3. +
    3. Post content +
      • The actual message of the post.
      +
      4. +
    4. Signature (sig) +
      • If the user has a signature set, it will show under each of their posts.
      +
      5. +
    5. Reactions +
      • This shows the emoji reactions users have added to the post, and you can add your own.
      +
      6. +
    +

    You may edit or delete your posts after creating them. Edited posts will show when they were edited instead of when they were posted.

    +

    You can quote another user's post by pressing the button on that post. This will copy the contents of it into the reply box and mention the user.

    +

    Posts are written in a markup language called Babycode. More information on it can be found in a separate guide.

    +
    +{% endblock %} diff --git a/app/templates/guides/user-guides/02-profiles.html b/app/templates/guides/user-guides/02-profiles.html new file mode 100644 index 0000000..55f2f1d --- /dev/null +++ b/app/templates/guides/user-guides/02-profiles.html @@ -0,0 +1,24 @@ +# User profiles +{% extends 'guides/_layout.html' %} +{% block guide_content %} +
    +

    User profiles

    +

    Each user on {{ config.SITE_NAME }} has a profile.

    +

    A user's profile shows:

    +
      +
    • Their avatar;
      • +
    • Their username and display name;
      • +
    • Their status;
      • +
    • Their signature;
      • +
    • Their stats: +
        +
      • Their permission level (regular user, moderator, etc);
        • +
      • The number of posts they've created;
        • +
      • The number of threads they've started;
        • +
      • A link to their latest started thread;
        • +
      • A few of their latest posts.
        • +
      +
      • +
    +
    +{% endblock %} diff --git a/app/templates/guides/user-guides/03-settings.html b/app/templates/guides/user-guides/03-settings.html new file mode 100644 index 0000000..6fbbbfe --- /dev/null +++ b/app/templates/guides/user-guides/03-settings.html @@ -0,0 +1,64 @@ +# User settings +{% extends 'guides/_layout.html' %} +{% block guide_content %} +
    +

    Settings

    +

    You can access your settings by following the "Settings" link in the top navigation bar or from the button in your profile.

    +

    The settings page lets you set your avatar, change your personalization options, and change your password.

    +
    +
    +

    Avatar

    +

    When you upload an avatar, keep in mind that it will be cropped to a square and resized to fit 256 by 256 pixels. It's best to upload an image that is already square. Avatars must be no more than 1 MB in size. You can also clear your avatar, resetting it to the default one.

    +

    To change your avatar, first press the button and select a file from your device, then press the button to upload it.

    +
    +
    +

    Personalization

    +

    The personalization section of the settings lets you change the following settings:

    +
      +
    • Theme +
        +
      • Set the appearance of the forum. This feature is still in beta and themes may change unexpectedly.
        • +
      +
      • +
    • Thread sorting +
        +
      • Set the sorting of threads when viewing a single topic. "Latest activity" will put threads which had a response more recently closer to the top. "Thread creation date" will put threads which were created more recently closer to the top.
        • +
      +
      • +
    • Display name +
        +
      • If set, your display name will show up instead of your username in most places. In a post's usercard, the display name will show up above your username/mention. In posts that have mentioned you, your display name will be shown instead of your @username.
        • +
      • Display names have fewer restrictions than usernames, and most characters are allowed.
        • +
      • If you do not wish to use a display name, you can leave the field blank.
        • +
      +
      • +
    • Status +
        +
      • If set, your status will show up below your @mention in a post's usercard. 100 characters limit, no Babycodes.
        • +
      +
      • +
    • Subscribe by default +
        +
      • If checked, you will automatically add the thread to your subscriptions when replying to it. You can override this setting by checking or unchecking "Subscribe to thread" before posting your reply in the reply box.
        • +
      +
      • +
    • Signature +
        +
      • If set, this signature will appear under all of your posts. Babycode is allowed (except @mentions).
        • +
      +
      • +
    +
    +
    +

    Changing your password

    +

    You can change your password by typing it in the "New password" field and again in the "Confirm new password" field, then pressing the button. The passwords in the two fields must match.

    +
    +
    +

    Deleting your account

    +

    If you no longer wish to participate in {{ config.SITE_NAME }}, you may delete your account. To do so, press the button in your settings, which will take you to a confirmation page.

    +

    Deleting your account is an irreversible action. Once you delete your account, you will not be able to log back in to it.

    +

    Deleting your account does not delete your threads and posts. They will be kept intact to preserve history. They will be altered to show up as if a system user authored them.

    +

    If you want your posts and threads to be deleted as well, you may either delete them yourself or contact the administrators for help.

    +

    If you're sure you want to delete your account, you will need to type your password on the confirmation page before pressing the button.

    +
    +{% endblock %} diff --git a/app/templates/guides/user-guides/04-inbox.html b/app/templates/guides/user-guides/04-inbox.html new file mode 100644 index 0000000..220b975 --- /dev/null +++ b/app/templates/guides/user-guides/04-inbox.html @@ -0,0 +1,29 @@ +# Inbox/subscriptions +{% extends 'guides/_layout.html' %} +{% block guide_content %} +
    +

    Subscriptions

    +

    You can subscribe to any thread. When subscribed, you will receive an overview of posts you missed for that thread in your inbox.

    +

    Additionally, when browsing a topic, threads you've subscribed to will show the number of posts you haven't read in it next to the thread's name.

    +
    +
    +

    Inbox

    +

    You can access your Inbox by following the "Inbox" link in the top navigation bar.

    +

    The Inbox is split into two parts:

    +
      +
    1. Subscriptions +
        +
      • A table of all threads that you've subscribed to. You can unsubscribe from each thread by pressing the button for that thread's row.
        • +
      • This section is collapsible, like a Babycode spoiler - press the "-" button to collapse it.
        • +
      +
      2. +
    2. Unread posts +
        +
      • These are the posts you missed in each thread, if any. They are sorted in reverse chronological order and are grouped by thread. Each thread is collapsible.
        • +
      • You can mark an entire thread as read by pressing the button, or unsubscribe from it by pressing the button.
        • +
      +
      3. +
    +

    Your inbox is updated automatically when you browse a subscribed thread. Once you've seen the posts you missed, they will disappear from your Inbox.

    +
    +{% endblock %} diff --git a/app/templates/guides/user-guides/05-bookmarks.html b/app/templates/guides/user-guides/05-bookmarks.html new file mode 100644 index 0000000..cdacee6 --- /dev/null +++ b/app/templates/guides/user-guides/05-bookmarks.html @@ -0,0 +1,39 @@ +# Bookmarks +{% from 'common/icons.html' import icn_bookmark %} +{% extends 'guides/_layout.html' %} +{% block guide_content %} +
    +

    Bookmarks

    +

    You can bookmark whole threads or individual posts to save them for later reading. Bookmarks are split into collections.

    +

    Each post or thread you bookmark (collectively bookmarks) can only belong to one collection.

    +

    Each bookmark can have a short memo that you can add to it, for example to help you remember why you saved it.

    +
    +
    +

    Bookmark collections

    +

    Bookmarks are organized into collections. There is always at least one collection you have access to, called "Bookmarks" by default.

    +

    You can add any number of collections by pressing the button on the your bookmarks page.

    +

    On the "Manage bookmark collections" page, you can add, delete, rename, and reorder your collections.

    +

    To add a new collection, press the button. A new item will be added.

    +

    You can name any collection by using the input box.

    +

    You can reorder collections by dragging and dropping it above or below others. The default collection is always at the top and can not be moved.

    +

    You can delete a collection by pressing the button on that collection. Deleting a collection will remove all bookmarks from it. If you delete a collection by accident, simply refresh the page. Your changes are not saved until you press the button.

    +
    +
    +

    Bookmarking posts and threads

    +
      +
    • To bookmark a thread, press the button at the top of the thread.
      • +
    • To bookmark a post, press the button on that post.
      • +
    +

    Both will bring up a popup with your bookmark collections. You can select the collection to save the bookmark into by pressing its name and add an optional memo. To save the bookmark, press the button. Each bookmark can only belong to one collection.

    +

    If the post or thread is already bookmarked, the name of the collection will be highlighed and the box to its name will be filled. If you wish to remove the bookmark, press the name of the collection it's in and press the button.

    +
    +
    +

    Browsing and managing bookmarks

    +

    You can access your bookmarks by following the "Bookmarks" link in the top navigation bar.

    +

    On the Bookmarks page, each collection will show up as a collapsible section. If a collection is empty, it will be collapsed.

    +

    If a collection has any bookmarks, it will have two collapsibe sections nested inside it: one for threads and one for posts.

    +

    Bookmarked threads are shown as a table with their title, the memo, and a button. Pressing this button will show the same popup, letting you move or remove the bookmark.

    +

    Bookmarked posts are shown in the same way they're shown in a thread. The memo will be shown before the post's time stamp. To the right of the post is the same button.

    +

    If you made changes to bookmarked threads or posts on this page, you will have to refresh to save those changes.

    +
    +{% endblock %} diff --git a/app/templates/guides/babycode.html b/app/templates/guides/user-guides/99-babycode.html similarity index 97% rename from app/templates/guides/babycode.html rename to app/templates/guides/user-guides/99-babycode.html index f26f61a..3bb137a 100644 --- a/app/templates/guides/babycode.html +++ b/app/templates/guides/user-guides/99-babycode.html @@ -1,17 +1,12 @@ -{% extends 'base.html' %} -{% from 'common/macros.html' import guide_sections with context %} -{% block title %}babycode guide{% endblock %} -{% block content %} -
    -

    Babycode guide

    -
    - -{% call() guide_sections() %} +# Babycode +{% extends 'guides/_layout.html' %} +{% block guide_content %}

    What is babycode?

    You may be familiar with BBCode, a loosely related family of markup languages popular on forums. Babycode is another, simplified, dialect of those languages. It is a way of formatting text by enclosing parts of it in special tags.

    A tag is a short name enclosed in square brackets. Tags can be opening tags, like [b] or closing tags, like [/b]. Anything inserted between matching opening and closing tags is known as the tag's content.

    Some tags can provide more specific instructions using an attribute. An attribute is added to the opening tag with an equals sign (=). This allows you to specify details like a particular color or a link's address.

    +

    Babycode is used in posts, user signatures, and MOTDs.

    Text formatting tags

    @@ -186,5 +181,4 @@
  • The [@] tag allows you to use the @ symbol without it being turned into a mention.
-{% endcall %} {% endblock %} diff --git a/config/pyrom_config.toml b/config/pyrom_config.toml index d11bfff..fc3bfed 100644 --- a/config/pyrom_config.toml +++ b/config/pyrom_config.toml @@ -11,3 +11,8 @@ USERS_CAN_INVITE = false # if true, allows users to create invite links. useless # some babycodes allowed # forbidden tags: [spoiler], [img], @mention, [big], [small], [center], [right], [color] ADMIN_CONTACT_INFO = "" + +# forum information. shown in the introduction guide at /guides/user/introduction +# some babycodes allowed +# forbidden tags: [spoiler], [img], @mention, [big], [small], [center], [right], [color] +GUIDE_DESCRIPTION = "" diff --git a/data/static/css/style.css b/data/static/css/style.css index f60b0f4..201c1e0 100644 --- a/data/static/css/style.css +++ b/data/static/css/style.css @@ -1340,7 +1340,7 @@ footer { justify-content: center; } -.babycode-guide-list { +.guide-list { border-bottom: 1px dashed; } diff --git a/data/static/css/theme-otomotone.css b/data/static/css/theme-otomotone.css index 98a7fb3..127753c 100644 --- a/data/static/css/theme-otomotone.css +++ b/data/static/css/theme-otomotone.css @@ -1340,7 +1340,7 @@ footer { justify-content: center; } -.babycode-guide-list { +.guide-list { border-bottom: 1px dashed; } diff --git a/data/static/css/theme-peachy.css b/data/static/css/theme-peachy.css index e6e8dd0..812e5c7 100644 --- a/data/static/css/theme-peachy.css +++ b/data/static/css/theme-peachy.css @@ -1340,7 +1340,7 @@ footer { justify-content: center; } -.babycode-guide-list { +.guide-list { border-bottom: 1px dashed; } diff --git a/sass/_default.scss b/sass/_default.scss index 707510f..391f798 100644 --- a/sass/_default.scss +++ b/sass/_default.scss @@ -1269,9 +1269,9 @@ $reaction_popover_padding: $SMALL_PADDING $MEDIUM_PADDING !default; justify-content: center; } -$babycode_guide_list_border: 1px dashed !default; -.babycode-guide-list { - border-bottom: $babycode_guide_list_border; +$guide_list_border: 1px dashed !default; +.guide-list { + border-bottom: $guide_list_border; } .bookmark-dropdown-inner {