Pages and Posts
A page is a page of information that is not categorized by date and time, category, or tag. (You are reading a page right now.) Conversely, a post is a content item that is categorized by date/time, and may be further categorized or tagged. Posts also appear in feeds, while pages do not. As they are both based on text content, many aspects of writing are the same between them.
The “Pages” and “Posts” menu items display a list of the current items of that type. Each list page is limited to 25 items; if there are more, there will be “Older” and “Newer” links at the bottom of each page that allow you to move to the next page. Posts are sorted by publishing date, with unpublished drafts at the top; pages are sorted by title. Both lists have an “Add” button at the top and “Edit” links below the titles.
Once you are editing a post or a page:
- Title is the title of the post or page; it is usually displayed prominently at the top of the page, in the browser's title bar, and is what is displayed in RSS readers.
- Permalink is the URL at which this post or page will be served; permalinks get their own section below.
- Page/Post Template is the theme template that will be used to render the content. By default, the
single-posttemplates will be used; however, if your theme contains any other templates that end with
-post, these appear here.
- Text has its own section below.
- (Pages) Show in Page List marks this page as one that should appear in a page list; the pages' titles and permalinks are available for template use. The default template renders the page list in the title bar.
- (Posts) Tags should be separated by commas, and should only contain lowercase letters, numbers, and spaces.
- (Posts) Publish This Post will show for unpublished drafts; checking that box will publish the post once it is saved.
- (Posts) Categories show as a list; assign categories by checking the box next to the name. Assign categories at the lowest subcategory level applicable; parent category lists will include posts from subcategories automatically.
- Metadata has its own section.
A permalink should not start with a slash, as one will be prepended when the blog base is, and must not use any characters that do no belong in a URL. A good permalink derives from the title; contains no spaces; and, for posts, may also contain date components. As an example, a post called “Jerry & Elaine” published in May 2022 could have the permalink
.html extension is not required; you can use whatever extension you would like, or none at all. URLs are checked for trailing slashes, whether present or missing, and if the URL is only off by this trailing slash, the browser will be redirected to the right one. (ex.
yadda-yadda-yadda will serve the same content).
One of the most frustrating things on the Internet is clicking a link, only to receive a
404 Not Found error. The term “permalink” is a portmanteau of “permanent link,” which implies that these links should be… well, permanent. myWebLog does its best to help with this. Whenever the Permalink field is changed, the previous value will be saved as a “prior permalink,” and if a request is made for the old one, myWebLog will redirect the browser to the new one. Say, for example, we had mistyped our permalink above as
jerry-adn-elaine.html; if we corrected the spelling, it will be fixed moving forward, and requests for the misspelled version will be redirected.
Extending that example - if we caught our mistake before the post was published, we do not need to maintain a permalink; it was a “working” permalink that was never publicly visible. There is a link below the Permalink field entitled “Manage Permalinks”; clicking this link will show the permalinks for the page or post. Within this page, you can remove any prior permalinks, and you can also add other permalinks. (myWebLog also has an option to import prior permalinks for existing content; that process is described in the Advanced Usage section.)
Page and Post Text
myWebLog supports text written in HTML and Markdown. (For the present time, you must enter the “source” version of these formats; WYSIWYG editors are a planned future feature.) This can be toggled at any time, so if you change your mind about a page or post, you can change it; and, if you write something in Markdown but forget to click the button, it's easy to go back in and switch it. (No, the person writing this has never done that - why do you ask?)
As you are writing, you may wish to link to other content within your blog. These links should be formatted with a single leading
/ and should be specified relative to your blog, even if it is not being served from the domain root. myWebLog will look for these links, and will render them with any directory information; when generating an RSS feed, these links are replaced with complete absolute links. Links that start with
https) are not translated, so linking to external content is not affected.
Whenever you change the text of a page or post, myWebLog will add it as the current revision, and save the prior revision. This enables you to restore a prior version if you desire. Underneath the Permalink field, there is a link entitled “Manage Revisions”; this page shows you all of the revisions of the page within the database. To see what one was, click the “Preview” link, and a preview of that version will be loaded below that line. If that is the revision you want to restore, click “Restore as Current”; it will become the current revision as of the current date/time.
This page also allows you to prune revisions, as they can take up space in your database. Each revision (apart from the current one) has a “Delete” link that will delete the revision without prompting. There is also a button at the top of the page that allows you to delete all prior revisions, but it will prompt you to be sure that is what you intended to do. (Note that the backups myWebLog creates only save the most recent revision, so keeping revisions will not cause backups to grow.)
If the post is a podcast episode, clicking the switch or label for “Podcast Episode” will display fields for all the possible information you can enter about that episode. Do not be overwhelmed, though; only 2 of them are required (plus 1 “strongly recommended”).
- Media File is the file name for the episode. If this starts with
http, it will be included as-is; if it does not, but the podcast's “Media Base URL” is provided, the media is appended to that base; if neither are true, it is rendered as a relative blog link.
- Length (in bytes) is the size of the media file in bytes; having this value in the feed lets podcast players know what they are going to be downloading. (There is a possible enhancement to allow the site to derive this automatically; however, it may not be done for version 2.)
- Duration, while not required, is highly recommended. This is a human-readable version of the running time of the episode. If an episode runs 45 minutes and 10 seconds, “00:45:10” would go in this field.
While those three fields will get the job done, there are several other fields available.
- Media MIME Type is used to override the podcast-level type. For example, if you have an audio podcast (
audio/mpegis the type for MP3 files), but want to release a video episode, placing
video/h264here will ensure that the media is rendered correctly.
- Subtitle is an optional subtitle to be displayed in the feed.
- Image URL links to the cover art for this episode. It is optional, and if omitted, the episode will use the podcast-configured image. Like the podcast image, a relative URL will be rendered for this blog, while an absolute URL will be rendered as-is.
- Explicit overrides the podcast-configured explicit rating.
- Chapter File links to a file with chapters for the podcast. The current specs for this file specify a JSON format for chapters; if the file here ends with
.json, it will be referenced with the
application/json+chaptersMIME type. If that needs to be overridden, enter your desired value in Chapter MIME Type.
- Transcript URL links to a transcript of the podcast; if it is provided, Transcript MIME Type is also required. If the transcript is in a different language than the podcast itself, enter a language code in the Transcript Language field. Finally, if the transcript file is designed to be used as captions, rather than read as a whole, check the This is a captions file box.
- Season Number is for podcasts released in seasons; leaving this blank or entering
0omits season information. Season Description provides a short description of the season; it is limited to 128 characters.
- Episode Number can be used in conjunction with seasons, or by itself. It supports numbers with up to 2 decimal places, and as with seasons, Episode Description can provide a short description.
In some cases, “page list” or categories/tags may not be sufficient for the information you wish to display. Both posts and pages support arbitrary metadata; this metadata can be accessed from theme templates. Both the name and value are free-form text; how you use that is dependent on your needs. (Liquid uses
lower_snake_case for its properties; using this for the name can help avoid errors between your metadata and the template rendering it.)
If you want to upload pictures or other content to include in your posts and pages, you can do that via the “Uploads” menu item.
Where Files Are Stored
There are two different options where myWebLog can store files - either on disk or in the database. On the web log settings page, you can specify the default destination for files, but you can change that selection each time you upload a file. There are some considerations as to which destination will fit your needs better.
- Files stored in the database do not require the server to write to the filesystem, and uploaded files are included in database backups. However, every backup will have every file, and if you upload frequently, it will grow large quickly. There is also slight overhead in retrieving the data for the file to serve it - though this can be negligible for smaller files (less than 100 KB).
- Files on disk can be served as static files, either by myWebLog itself or by another web server (if myWebLog is running behind a reverse proxy). This is faster than retrieving the data from the database. These files are not included in database backups, which keeps them trim; however, you will need a different strategy to back up these files. The files are stored in year and month directories, which can be used in an incremental backup process (run outside of myWebLog).
However you store them, there is an upper limit to the size of a file that can be uploaded. If you are running myWebLog directly, its limit is 30 MB; if you are running it behind a reverse proxy server, it may enforce smaller limits. Also, both database and disk files are served from the path
upload/[blog-slug]/[year]/[month]. For example, if we uploaded
haha.jpg to our “A Blog about Nothing” on June 18th, 2021, the path would be
Uploading a File
Click the “Upload a New File” button. You will then have a field where you can select the file, and a selection for the destination. When you submit the form, the file will be uploaded, and you will see the list of files, with the one you just uploaded near* the top. (*sorting may be off for files on disk, as we cannot reliably get their last modified time.)
Getting the File's URL
From the file list, there are either two or three selections after “Copy”, just below the name of the file. Absolute is a link that will work wherever you put it; it can be used to link to that file from outside the site. Relative is a link that is relative to your server; if your server is running at the root of the domain, this is the link you will want to put in a post or page. If your server is running in a directory, there will be a third option For Post; this will be the link to use for the post, while Relative will allow you to link to the file from another directory on the server.
From the file list, there is a “Delete” link. Click that link, confirm that is what you want to do, and the file will be deleted. The deletion will work the same no matter where the file is stored.