@title Phame User Guide
@group userguide

Phame is a blogging platform.

Overview
========

Phame is a simple platform for writing blogs and blog posts. Content published
through Phame is integrated with other Phabricator applications (like Feed,
Herald and Dashboards).

You can use Phame to write and publish posts on any topic. You might use it to
make announcements, hold discussions, or provide progress updates about a
project.

In the upstream, we use several Phame blogs to discuss changes to Phabricator,
make company announcements, photograph food, and provide visionary thought
leadership.


Blogs
=====

To get started with Phame, create a blog. Blogs can be personal or edited
by a group: the **Editable By** policy controls who is allowed to write new
posts.

You can provide a title, subtitle, and description to help users understand
the role and purpose of the blog.

After creating a blog, you can optionally provide a header image (a large
image shown on the main blog page, like a beautiful photograph of food) and
a picture (a small logo or profile image shown in various places in the UI to
help identify the blog).

Blogs can also be hosted externally. See "External Blogs", below, for
more information.


Posts
=====

After creating a blog, you're ready to write your first post. You can navigate
to the blog and choose {nav Write Post} to get started.

Posts have a **Visibility** field which controls who can see them. The options
are:

  - **Published**: Anyone who can see the blog will be able to read the post.
  - **Draft**: Allows you to work on posts before publishing them. Only users
    who can edit the blog will be able to see the post.
  - **Archived**: Allows you to remove old posts. Only users who can edit
    the blog will be able to see the post, and it won't appear in the pending
    drafts list.

After publishing a post, it will appear on the blog and on the Phame home page
for all users who can see it.


Using Phame With Other Applications
===================================

Phame integrates with other Phabricator applications, so you can do a few
interesting things:

**Dashboards**: You can create a dashboard panel which shows posts on a
particular blog, then put the panel on the homepage or a custom dashboard.

This is an easy way to create a list of recent announcements.

**Herald**: You can use Herald rules to make sure you get notified whenever
your favorite author publishes a new post.

**Remarkup**: You can reference a blog post in any other application using the
`J123` monogram for the post, or embed a more detailed link with `{J123}`.

(We ran out of letters a while ago, but thinking about **j**ournal may be
helpful in remembering this.)


External Blogs
==============

WARNING: This feature is still a prototype and has some known issues.

You can host a Phame blog on an external domain, like `blog.mycompany.com`. The
Phacility corporate blog is an example of an external Phame blog:

> https://blog.phacility.com/

External blogs are public (they do not require login) and are only supported if
your Phabricator install is also public. You can make an install public by
adjusting `policy.allow-public` in Config, but make sure you understand the
effects of adjusting this setting before touching it.

Once you've made your install public, configure the blog that you want to host
like this:

  - **View Policy**: Set the "View Policy" for the blog to "Public". Blogs must
    have a public view policy to be served from an external domain.
  - **Full Domain URI**: Set this to the full URI of your external domain,
    like `https://blog.mycompany.com/`. When users visit this URI, Phabricator
    will serve the blog to them.

To configure the blog's navigation breadcrumbs so that it links back to the
right parent site, set these options:

  - **Parent Site Name**: Put the parent site name here (like "MyCompany").
  - **Parent Site URI**: Put the parent site URI here (like
    `https://www.mycompany.com`).

Configuring these options will add a new breadcrumb to the navigation to let
users return to the blog's parent site. It will look something like this:

  - {nav My Company > Blog Name}

Finally, configure DNS for `blog.mycompany.com` to point at Phabricator.

If everything is set up properly, visiting `blog.mycompany.com` should now
serve your blog.
