Document process for publishing on blog

[gpsaggese]

We want to document:

1. What is the authorship policy for blog entry

   • It's everyone who helped (e.g., writing code, reviewing code, writing the blog, etc)

2. In practice we want to have a simple system where one of our markdown docs becomes a blog entry

   • Pros
     • Helps with making sure people spend effort documenting nicely (e.g., with plots)
     • Use Diataxis
     • We can source control the blog entry (e.g., with a ping back to the repo and hash) so if the documentation is updated also the blog is

Next steps

• [x] The blog can be called "Causify Research Blog"
• [ ] Use tags to categorize blog entries
• [x] Come up and document with a process to "push a md to the blog"
• [ ] We want to push the 4-5 that we have ready
• [ ] Once we have enough meat, we'll start cross-posting (on LinkedIn, Substack)

[Shayawnn]

• The Causify Blog Platform Documentation outlines how to log in, create content, invite staff, and maintain the Causify Blog.

[gpsaggese]

@aangelo9 can you pls take a look at this and use #843 and #848 as example?

I would

• [x] start reading the gdoc and convert it into a markdown and
• [x] use your work as example
• [x] ask @heanhsok and @Shayawnn for help on the process

[aangelo9]

@Shayawnn I would like to request access to the gdoc.

[gpsaggese]

Perms given

[aangelo9]

@Shayawnn @heanhsok Can I get a staff invite for the blog platform to test out publishing?

[heanhsok]

@aangelo9 We sent you a contributor invite via email. Could you try to sign up? You'll be able to create and edit your own posts, but to publish, you'll need approval.

[aangelo9]

Understood, I have successfully signed up.

[aangelo9]

Problem

I have encountered a problem where linked text from the Markdown appears in black, which blends in with the black background of the website. From my understanding, only admin/staff can change the blog format.

Solution

• Remove TOC and any linked text in the file temporarily
• Edit the theme & design of the blog

WDYT? @heanhsok

[heanhsok]

I see. I think it's better to keep the hyperlinks. Maybe @Shayawnn can help check the theme?

[aangelo9]

Problem

For the authorship policy for blog entry, Ghost can only have one author per post.

Solution

We could add an Authorship section at the end of the blog.

## Authorship

- gpsaggese – developed the supporting code and workflows  
- aangelo9 – authored the documentation and blog post
- Shayawnn, heanhsok – managed the publishing process, reviewed the documentation and blog content  

FYI contributor level access do not have the ability to add tags or edit the blog author, so reviewers will need to add tags themselves.

WDYT? @gpsaggese @heanhsok @Shayawnn

[gpsaggese]

1. Sure, let's change the theme for now so we can make it readable

2. Weird limitation on having only one author. I like using GitHub users. I'm okay with just saying the authors are XYZ without going into details (we do what you have proposed for journal papers, but for a blog, there seem to be too many details).

3. Yes, we can have authors in the text, if there is no other way

4. Can you start documenting these decisions we are making in a Gdoc or markdown? There are several interns woking on blogs and we want to point them to a doc (even if it's not finished)

[aangelo9]

After some more research, Ghost does support multiple authors. However, it only displays the one who created the post by default. Displaying multiple authors is possible by editing the theme. Could you check this out @Shayawnn?

For now, I’ll include the ## Authorship section in the markdown. We can update the markdown instructions to add authors directly once displaying multiple authors is fully supported.

@gpsaggese Doc is ready in PR #856.

Here is the post draft link for #843.

[gpsaggese]

@Shayawnn can you pls send over the credentials?

I'll save them in 1Password as always

[Shayawnn]

@Shayawnn can you pls send over the credentials?

I'll save them in 1Password as always

@gpsaggese Resent the invitation, Please confirm

[gpsaggese]

Thanks @Shayawnn I'm in

1. Let's move the authors first at the top of the blog
2. We'll work on improving the style (e.g., the Python code should be rendered better)
3. Can we make the page larger?
4. Can we look for some cool template to style it? It doesn't have to be perfect, just a little bit better. We'll get a graphic designer to make it swanky

The current goal is to put out as much material and then we'll make it perfect. Good job @aangelo9

[aangelo9]

1. Let's move the authors first at the top of the blog

I checked the blog preview, and displaying multiple authors has been implemented.

1. Since "Contributors" access do not have the ability to add authors to posts, we should have them add the ## Authorship section at the top of the post draft, so that reviewers could add authors properly, and then delete the ## Authorship section before publishing.

2. I will update the how-to publishing doc after things are finalized.

[Shayawnn]

Design tweaks

Every author now shows in the byline (no more "one-author-only" limitation) + layout & readability tweaks were applied.

@gpsaggese Looking good?

[aangelo9]

Could we increase the line/content width to follow linters' 80 chars per line, since it creates weird line breaks?

[gpsaggese]

Nice improvements. Thanks @Shayawnn

• Yes larger line is perfect.
• We can also add our pics (ideally the one we use on GitHub), so that we push everyone to have a decent one

[Shayawnn]

content-width issue fixed

The column is now at 80 ch;

FYI., @aangelo9—while patching the styles I accidentally cleared the drafted post in the editor.
I restored it by pasting the Markdown from the repo, but please skim it once more to be safe.

Other tweaks

• Uploaded avatars for @gpsaggese, @Shayawnn and @heanhsok so the multi-author header shows faces.
  • @aangelo9 Your profile is faceless; please add one.

[gpsaggese]

Is there a way to make it as large as the screen? It's weird otherwise. Also does it render ok on mobile? I'm sure ghost has tons of options to make things look nice.

[aangelo9]

FYI., @aangelo9—while patching the styles I accidentally cleared the drafted post in the editor. I restored it by pasting the Markdown from the repo, but please skim it once more to be safe.

Moved content into a Markdown card.

• @aangelo9 Your profile is faceless; please add one.

Done.

[aangelo9]

On #843, I added a mermaid plot to visualize Git branches and commits on https://blog.causify.ai/ghost/#/editor/post/68531a0960acd50001c33c17.

To achieve this:

1. On Code injection, under Post header {{ghost_head}}, I added:

   <script type="module">
     import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
     mermaid.initialize({ startOnLoad: true });
   </script>
   

2. Wrapped mermaid code with HTML block tag:

   <pre class="mermaid">
   %%{init: {'theme': 'base', 'gitGraph': {'mainBranchName': 'master'}}}%%
   gitGraph
       commit id: "Initial commit (master)"
       branch CmTask5874_Document_PR_flow
       checkout CmTask5874_Document_PR_flow
       commit id: "Feature change 1"
       commit id: "Feature change 2"
       checkout master
       branch CmTask5874_Document_PR_flow_2
       checkout CmTask5874_Document_PR_flow_2
       merge CmTask5874_Document_PR_flow id: "Squash feature changes"
       commit id: "Commit .png files only"
       checkout master
       merge CmTask5874_Document_PR_flow_2 id: "Partial PR merged"
       checkout CmTask5874_Document_PR_flow
       merge master id: "Sync with master"
   </pre>
   

We may want to enable Mermaid globally by either using global code injection or by adding it directly to the theme.

[gpsaggese]

@Shayawnn can / should we enable that?

Another approach is to use our render_image flow which supports more rendering. You can read the documentation and get a sense aboutit, @aangelo9 WDYT?

[aangelo9]

Another approach is to use our render_image flow which supports more rendering. You can read the documentation and get a sense aboutit, @aangelo9 WDYT?

This can work. So instead of having the mermaid code block, we have the rendered image in its place. We can upload the image to the repo and have the blog point to it like so (in the Markdown card):

![Causify Blog Image](https://raw.githubusercontent.com/causify-ai/helpers/master/docs/tools/figs/blog/image1.png)

[gpsaggese]

1. Yes, personally I'd prefer to use render_images so that it's more general and we don't depend on the platform for doing the rendering.

2. Where to put the images?

• Yes, we can save them in the repo and then extend render_images to use absolute references, when there is a switch --use_github_hosting. Can you pls file an issue and extend render_images.py? Feel free to make a design PR or a proposal on GH