src/docs/user/userguide/phame.diviner

   1 @title Phame User Guide
   2 @group userguide
   3
   4 Phame is a blogging platform.
   5
   6 Overview
   7 ========
   8
   9 Phame is a simple platform for writing blogs and blog posts. Content published
  10 through Phame is integrated with other Phabricator applications (like Feed,
  11 Herald and Dashboards).
  12
  13 You can use Phame to write and publish posts on any topic. You might use it to
  14 make announcements, hold discussions, or provide progress updates about a
  15 project.
  16
  17 In the upstream, we use several Phame blogs to discuss changes to Phabricator,
  18 make company announcements, photograph food, and provide visionary thought
  19 leadership.
  20
  21
  22 Blogs
  23 =====
  24
  25 To get started with Phame, create a blog. Blogs can be personal or edited
  26 by a group: the **Editable By** policy controls who is allowed to write new
  27 posts.
  28
  29 You can provide a title, subtitle, and description to help users understand
  30 the role and purpose of the blog.
  31
  32 After creating a blog, you can optionally provide a header image (a large
  33 image shown on the main blog page, like a beautiful photograph of food) and
  34 a picture (a small logo or profile image shown in various places in the UI to
  35 help identify the blog).
  36
  37 Blogs can also be hosted externally. See "External Blogs", below, for
  38 more information.
  39
  40
  41 Posts
  42 =====
  43
  44 After creating a blog, you're ready to write your first post. You can navigate
  45 to the blog and choose {nav Write Post} to get started.
  46
  47 Posts have a **Visibility** field which controls who can see them. The options
  48 are:
  49
  50   - **Published**: Anyone who can see the blog will be able to read the post.
  51   - **Draft**: Allows you to work on posts before publishing them. Only users
  52     who can edit the blog will be able to see the post.
  53   - **Archived**: Allows you to remove old posts. Only users who can edit
  54     the blog will be able to see the post, and it won't appear in the pending
  55     drafts list.
  56
  57 After publishing a post, it will appear on the blog and on the Phame home page
  58 for all users who can see it.
  59
  60
  61 Using Phame With Other Applications
  62 ===================================
  63
  64 Phame integrates with other Phabricator applications, so you can do a few
  65 interesting things:
  66
  67 **Dashboards**: You can create a dashboard panel which shows posts on a
  68 particular blog, then put the panel on the homepage or a custom dashboard.
  69
  70 This is an easy way to create a list of recent announcements.
  71
  72 **Herald**: You can use Herald rules to make sure you get notified whenever
  73 your favorite author publishes a new post.
  74
  75 **Remarkup**: You can reference a blog post in any other application using the
  76 `J123` monogram for the post, or embed a more detailed link with `{J123}`.
  77
  78 (We ran out of letters a while ago, but thinking about **j**ournal may be
  79 helpful in remembering this.)
  80
  81
  82 External Blogs
  83 ==============
  84
  85 WARNING: This feature is still a prototype and has some known issues.
  86
  87 You can host a Phame blog on an external domain, like `blog.mycompany.com`.
  88
  89 External blogs are public (they do not require login) and are only supported if
  90 your Phabricator install is also public. You can make an install public by
  91 adjusting `policy.allow-public` in Config, but make sure you understand the
  92 effects of adjusting this setting before touching it.
  93
  94 Once you've made your install public, configure the blog that you want to host
  95 like this:
  96
  97   - **View Policy**: Set the "View Policy" for the blog to "Public". Blogs must
  98     have a public view policy to be served from an external domain.
  99   - **Full Domain URI**: Set this to the full URI of your external domain,
 100     like `https://blog.mycompany.com/`. When users visit this URI, Phabricator
 101     will serve the blog to them.
 102
 103 To configure the blog's navigation breadcrumbs so that it links back to the
 104 right parent site, set these options:
 105
 106   - **Parent Site Name**: Put the parent site name here (like "MyCompany").
 107   - **Parent Site URI**: Put the parent site URI here (like
 108     `https://www.mycompany.com`).
 109
 110 Configuring these options will add a new breadcrumb to the navigation to let
 111 users return to the blog's parent site. It will look something like this:
 112
 113   - {nav My Company > Blog Name}
 114
 115 Finally, configure DNS for `blog.mycompany.com` to point at Phabricator.
 116
 117 If everything is set up properly, visiting `blog.mycompany.com` should now
 118 serve your blog.