myWebLog
Writing

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.

Writing Content

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-page and single-post templates will be used; however, if your theme contains any other templates that end with -page or -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.

Permalinks

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 2022/05/jerry-and-elaine.html. The .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/ and 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 http (including https) are not translated, so linking to external content is not affected.

Revisions

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.)

Podcast Episodes

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/mpeg is the type for MP3 files), but want to release a video episode, placing video/h264 here 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.
• Chapters defines where chapter information for this episode can be found. “None” means that there are no chapters. “Defined Here” will allow chapters to be maintained within myWebLog (see Episode Chapters below). “Separate File” enables the Chapter File and Chapter MIME Type, allowing you to specify the JSON chapter file; if it ends in .json, the MIME type will be application/json+chapters, though the MIME type field allows you to override that. Setting Contains Waypoints tells compatible applications that the sequence of locations in the chapter file constitute physical waypoints (for example, a walking tour of a city).
• 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 0 omits 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.

Episode Chapters

When the chapter selection “Defined Here” is chosen, there will be a link just below the permalink field that says “Manage Chapters”. This link lists the current chapters, and allows you to define others. Each chapter consists of:

• Start Time is the only required field, and serves as the marker for when the chapter begins. It may be entered in total seconds (4320), total minutes with seconds (72:15), or total hours with minutes and seconds (1:12:15). Fractional seconds may be entered to 9 digits, but only the hundredths will be tracked. Regardless of how the time is originally entered, it will be displayed as 1:12:15.22.
• End Time is when the chapter ends. In practice, however, a chapter also ends when a new chapter begins or when the media file ends; this field will likely be used rarely. It supports the same formats as Start Time.
• Chapter Title is the name of the chapter; it is what is displayed in some podcast applications to identify the chapter to its users.
• Image URL is artwork specifically for this chapter. Relative URLs will be assumed to point to pages on the site, while those starting with http or https will link to external sites.
• URL is a link for more information about the contents of this chapter.
• Hidden Chapter means that this chapter will not be shown in applications that show chapters. This can be used to update artwork or locations, but have the application still show the prior chapter's name.
• Associate Location will allow a location to be associated with the chapter. If this is selected, Name and Geo URL are required, while OpenStreetMap ID is optional.

A few other notes on chapters:

• When adding chapters “Add Another Chapter” is preselected; this allows you to press Enter to save the chapter, and the page will load a fresh form with the cursor in the Start Time field. The goal here is to enable fast entry of these chapters without requiring you to take your hands off the keys. If you forget to deselect it on your last chapter, just press Cancel.
• Chapters will always be sorted by start time.
• Chapters can be edited and deleted.
• The chapters will be served from the same URL as the post to which they are assigned, with ?chapters added to the end.

Metadata

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.)

Uploaded Content

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 18^th, 2021, the path would be upload/a-blog-about-nothing/2021/06/haha.jpg.

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.

Deleting Files

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.

« myWebLog Home View Source Repo