From 172ecdb9a23f0d893c197a4fb001c0c831f7a89e Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 4 Mar 2021 13:47:18 -0700 Subject: [PATCH 1/5] Add changes from https://github.com/ipfs/ipfs-blog/pull/71 --- README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fceab869..ac06df82 100644 --- a/README.md +++ b/README.md @@ -9,14 +9,22 @@ This work is part of a larger product-market fit realignment/enhancement effort ⚠️⚠️⚠️ **If you want to publish a blog post, don't do it here yet** — use [the existing blog](https://github.com/ipfs/blog) instead! -## Authoring/deployment workflow +## Workflow for post authors/editors -This blog uses the `staging` branch as a work-in-progress scratchpad, with the production site deployed from `main` via [Fleek](https://fleek.co/). +This blog uses the `staging` branch as a work-in-progress scratchpad for blog content, with the production site deployed from `main` via [Fleek](https://fleek.co/). We use [Forestry](https://forestry.io) as a CMS-style environment, including perks like WYSIWYG editing and image upload/crop tools. If you're an IPFS core team member and don't have Forestry access, contact @jessicaschilling to arrange access and a quick orientation session. (If you prefer writing in Markdown, don't fear: Forestry also has a raw Markdown view.) Forestry writes directly to `staging`, with previews available at https://ipfs-blog-staging.on.fleek.co/. Once a staged post is ready to go live, please PR `staging` to `main` using [this handy shortcut](https://github.com/ipfs/ipfs-blog/compare/main...staging?expand=1). *Note that if multiple posts are in-flight in staging and only one is approved to go live, your PR may need some massaging.* +### Just want to add a new "link card"? + +Foo foo foo + +## Workflow for site developers + +All development PRs (as opposed to blog posts) should be merged into `main`. + ## License © Protocol Labs | Code is licensed with the [MIT](LICENSE) License. Except as noted, other content licensed [CC-BY 3.0](https://creativecommons.org/licenses/by/3.0/us/). From 7f06777468adc2afe076c6693eaec63e4a0f9784 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 4 Mar 2021 14:43:13 -0700 Subject: [PATCH 2/5] More developer instructions --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ac06df82..84c9d310 100644 --- a/README.md +++ b/README.md @@ -11,19 +11,63 @@ This work is part of a larger product-market fit realignment/enhancement effort ## Workflow for post authors/editors -This blog uses the `staging` branch as a work-in-progress scratchpad for blog content, with the production site deployed from `main` via [Fleek](https://fleek.co/). +This site uses the `staging` branch as a work-in-progress scratchpad for blog content. Once approved for go-live, `staging` is merged into `main`; the production site is automatically deployed from the latest `main` using [Fleek](https://fleek.co/). -We use [Forestry](https://forestry.io) as a CMS-style environment, including perks like WYSIWYG editing and image upload/crop tools. If you're an IPFS core team member and don't have Forestry access, contact @jessicaschilling to arrange access and a quick orientation session. (If you prefer writing in Markdown, don't fear: Forestry also has a raw Markdown view.) +Post authors and editors are strongly encouraged to use this site's [Forestry](https://forestry.io) integration for drafting and editing, including perks like WYSIWYG editing and image upload/crop tools. If you're an IPFS core team member and don't have Forestry access, contact @jessicaschilling to arrange access and a quick orientation session. (If you prefer writing in Markdown, don't fear: Forestry also has a raw Markdown view.) + +### Forestry tips + +Foo + +### To deploy to the live site Forestry writes directly to `staging`, with previews available at https://ipfs-blog-staging.on.fleek.co/. Once a staged post is ready to go live, please PR `staging` to `main` using [this handy shortcut](https://github.com/ipfs/ipfs-blog/compare/main...staging?expand=1). *Note that if multiple posts are in-flight in staging and only one is approved to go live, your PR may need some massaging.* ### Just want to add a new "link card"? -Foo foo foo +Feel free to use Forestry to add details for "link cards" like videos, release notes or news items, and submit a PR for review/merge. However, if you're in a hurry, simply fill in the [public submission form](https://airtable.com/shrNH8YWole1xc70I) and a site maintainer will take care of the rest. ## Workflow for site developers -All development PRs (as opposed to blog posts) should be merged into `main`. +**Important!** All site development forks/PRs (as opposed to blog posts) should be based on and merged into `main`. + +This site is built in [Vuepress](https://vuepress.vuejs.org/guide/), and uses Vue/JavaScript for functional code and Markdown for post content. + +### Build and run locally +To build a local copy, run the following: + +1. Clone this repository: + + ```bash + git clone https://github.com/ipfs/ipfs-blog.git + ``` + +1. Move into the `ipfs-blog` folder and install the NPM dependencies: + + ```bash + cd ipfs-docs + npm install + ``` + +1. Boot up the application in _dev mode_: + + ```bash + npm start + ``` + +1. Open [localhost:8080](http://localhost:8080) in your browser. +1. Close the local server with `CTRL` + `c`. +1. To restart the local server, run `npm start` from within the `ipfs-blog` folder. + +### PR and preview +Once you're happy with your local changes, please make a PR against the `main` branch. Including detailed notes on your PR helps smooth the approval and deployment process, so make sure to thoroughly document your changes, including screenshots to depict any changes in UI. + +PRs against `main` will automatically generate Fleek previews for ease of review. A successful run of a Fleek preview build generates a live preview viewable by clicking `Details` in the `fleek/build` check at the bottom of your PR page: +![image](https://user-images.githubusercontent.com/1507828/110034382-9dbb5b80-7cf7-11eb-89a4-7772970677d3.png) + +## Maintainers + +This site is under active maintenance by members of the core [IPFS team](https://ipfs.io/team/). ## License From 01f81bcfc998b489fb753fbf345403f21432edde Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 4 Mar 2021 14:50:04 -0700 Subject: [PATCH 3/5] Clarify dev instructions --- README.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 84c9d310..aafdec50 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,17 @@ [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) -This repository is home to in-development work on a VuePress/Forestry-based IPFS blog to replace [the existing IPFS blog](https://blog.ipfs.io). Target go-live is in late Q1 2021. Contact @jessicaschilling with any questions. +This repository is home to in-development work on a VuePress/Forestry-based replacement for [the existing IPFS blog](https://blog.ipfs.io). Target go-live is in late Q1 2021. Contact @jessicaschilling with any questions. This work is part of a larger product-market fit realignment/enhancement effort on the IPFS website as a whole. [View tracking board.](https://github.com/orgs/ipfs/projects/11) -⚠️⚠️⚠️ **If you want to publish a blog post, don't do it here yet** — use [the existing blog](https://github.com/ipfs/blog) instead! +⚠️⚠️⚠️
**If you want to publish a blog post, don't do it here yet** — use [the existing blog](https://github.com/ipfs/blog) instead!
⚠️⚠️⚠️ ## Workflow for post authors/editors This site uses the `staging` branch as a work-in-progress scratchpad for blog content. Once approved for go-live, `staging` is merged into `main`; the production site is automatically deployed from the latest `main` using [Fleek](https://fleek.co/). -Post authors and editors are strongly encouraged to use this site's [Forestry](https://forestry.io) integration for drafting and editing, including perks like WYSIWYG editing and image upload/crop tools. If you're an IPFS core team member and don't have Forestry access, contact @jessicaschilling to arrange access and a quick orientation session. (If you prefer writing in Markdown, don't fear: Forestry also has a raw Markdown view.) +Post authors and editors are strongly encouraged to [use this site's Forestry integration](https://forestry.io) for drafting and editing, including perks like WYSIWYG editing and image upload/crop tools. If you're an IPFS core team member and don't have Forestry access, contact @jessicaschilling to arrange access and a quick orientation session. (If you prefer writing in Markdown, don't fear: Forestry also has a raw Markdown view.) ### Forestry tips @@ -29,11 +29,11 @@ Feel free to use Forestry to add details for "link cards" like videos, release n ## Workflow for site developers -**Important!** All site development forks/PRs (as opposed to blog posts) should be based on and merged into `main`. - -This site is built in [Vuepress](https://vuepress.vuejs.org/guide/), and uses Vue/JavaScript for functional code and Markdown for post content. +**Important!** All site development forks/PRs (as opposed to blog posts) should be based on and merged into `main`, **not** `staging`. ### Build and run locally +This site is built in [Vuepress](https://vuepress.vuejs.org/guide/), and uses Vue/JavaScript for functional code and Markdown for post content. + To build a local copy, run the following: 1. Clone this repository: @@ -60,11 +60,13 @@ To build a local copy, run the following: 1. To restart the local server, run `npm start` from within the `ipfs-blog` folder. ### PR and preview -Once you're happy with your local changes, please make a PR against the `main` branch. Including detailed notes on your PR helps smooth the approval and deployment process, so make sure to thoroughly document your changes, including screenshots to depict any changes in UI. +Once you're happy with your local changes, please make a PR **against the `main` branch**. Including detailed notes on your PR helps smooth the approval and deployment process, so make sure to thoroughly document your changes, including screenshots to depict any changes in UI. PRs against `main` will automatically generate Fleek previews for ease of review. A successful run of a Fleek preview build generates a live preview viewable by clicking `Details` in the `fleek/build` check at the bottom of your PR page: ![image](https://user-images.githubusercontent.com/1507828/110034382-9dbb5b80-7cf7-11eb-89a4-7772970677d3.png) +A reviewer will be by shortly to have a look! + ## Maintainers This site is under active maintenance by members of the core [IPFS team](https://ipfs.io/team/). From 899eebf42346c12ec5ffc6445945deedb736fdae Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 4 Mar 2021 15:27:13 -0700 Subject: [PATCH 4/5] Writer/editor guidance --- README.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index aafdec50..6f782253 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,25 @@ This work is part of a larger product-market fit realignment/enhancement effort This site uses the `staging` branch as a work-in-progress scratchpad for blog content. Once approved for go-live, `staging` is merged into `main`; the production site is automatically deployed from the latest `main` using [Fleek](https://fleek.co/). -Post authors and editors are strongly encouraged to [use this site's Forestry integration](https://forestry.io) for drafting and editing, including perks like WYSIWYG editing and image upload/crop tools. If you're an IPFS core team member and don't have Forestry access, contact @jessicaschilling to arrange access and a quick orientation session. (If you prefer writing in Markdown, don't fear: Forestry also has a raw Markdown view.) +Post authors and editors are strongly encouraged to [use this site's Forestry integration](https://forestry.io) for drafting and editing, including perks like WYSIWYG editing image upload/crop tools, and instant previews. If you're an IPFS core team member and don't have Forestry access, contact @jessicaschilling to arrange access and a quick orientation session. (If you prefer writing in Markdown, don't fear: Forestry also has a raw Markdown view.) -### Forestry tips +### Forestry authoring/editing tips -Foo +- Use the "Content Types" section of the left-hand menu to drill down to the type of item (e.g. blog post, video, news coverage, event) you want to create or edit. +- Use the [image crop/scale tool](https://ipfs-blog.on.fleek.co/image-crop/) to resize and save images so they're the perfect dimensions for link cards and blog post header images. (Don't have an image? Don't worry; the site falls back to generic images in all cases.) +- If you're in edit mode for a blog post, you can switch between WYSIWYG and raw Markdown (for example, if you want to add HTML embed code to the Markdown) by choosing "Raw Editor/WYSIWYG Editor" from the dots menu at the top right of the page:
![image](https://user-images.githubusercontent.com/1507828/110036257-fbe93e00-7cf9-11eb-935c-a70f9d21c14f.png) + +### Forestry build preview tips +While WYSIWYG mode can often give you a good enough idea of what a blog post will look like, you can also load Forestry's built-in _build preview_ in a new tab by clicking the eye icon at the top right of the page:
![image](https://user-images.githubusercontent.com/1507828/110036918-f4766480-7cfa-11eb-9cf3-a0082e61a7a0.png) + +This build preview lets you preview changes to any content type (not just blog posts), and _does not_ require you to save your changes in order to see them. + +Other tips for using Forestry build previews: +- Click the eye icon to regenerate a build preview at any time from the edit page. You may need to reload the build preview page if you don't see changes come through immediately. +- Occasionally, a build preview page gets stuck at a URL ending in `forestry/pending` or simply won't load. Try these troubleshooting tips: + - Remove `forestry/pending` from the URL and try again. + - Check the Previews section of Forestry's [`Site > Settings` page](https://app.forestry.io/sites/lg5t7mxcqbr-da/#/settings/previews) to see the preview server's current status, start/stop/restart the server, or examine the logs for errors. Simply restarting the preview server can correct a multitude of problems. + - If all else fails, save your changes, wait a few minutes, and take a look at [Fleek's build of the latest version of the `staging` branch](https://ipfs-blog-staging.on.fleek.co/). It's a considerably slower build/deploy time, but does reflect the latest changes once it finishes deploying. ### To deploy to the live site From 76dc532052772b253324c3850918f6db44c44bce Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 4 Mar 2021 15:40:12 -0700 Subject: [PATCH 5/5] Eye candy --- README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6f782253..847ff8b0 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,12 @@ -# IPFS Blog (v2 Beta) +# IPFS Blog & News -[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai) -[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) +[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg)](https://protocol.ai) +[![](https://img.shields.io/badge/project-IPFS-blue.svg?)](http://ipfs.io/) +[![](https://img.shields.io/badge/platform-VuePress-green.svg)](https://vuepress.vuejs.org/) +[![](https://img.shields.io/badge/cms-Forestry-000000.svg)](https://forestry.io) +[![](https://img.shields.io/badge/deployed%20on-Fleek-ff69b4.svg)](http://fleek.co/) + +![Picture of IPFS blog displayed on a laptop](https://user-images.githubusercontent.com/1507828/110040308-d2331580-7cff-11eb-8a05-8f5bad5ca819.png) This repository is home to in-development work on a VuePress/Forestry-based replacement for [the existing IPFS blog](https://blog.ipfs.io). Target go-live is in late Q1 2021. Contact @jessicaschilling with any questions.