Ghost 1.0.0 Documentation

[ErisDS]

This issue is a placeholder for keeping a list of documentation we're going to need to write/rewrite for Ghost 1.0.0.

pre-tasks from meeting

• help.ghost.org - stays as is
• themes.ghost.org stays as it
• docs.ghost.org - die, but it will be the new developers/core documentation
• [x] http://support.ghost.org - migrate to docs.ghost.org @cobbspur
• [ ] academy.ghost.org - die (move to help.ghost.org) - @frantzypants will care
• [x] move github wiki to docs.ghost? (except of contributing.md, which links to readme) which includes tooling, apps, how to develop with server/client etc @kevinansfield @kirrg001
• [x] @sebgie support.ghost.org dies

required

@AileenCGN

• [x] http://themes.ghost.org/ + documentation for package.json theme validation
• [x] from #8348: additional theme documentation updates
• [x] new error templates. base / 5xx errors should never use any helpers other than asset.
• [x] mail config
• [x] ghost.org/developers shows API, themes, core (developers) and docs.ghost.org

@kirrg001

• [x] How to use the new config (http://support.ghost.org/config)
• [x] How to use the new CLI installer
• [x] improve working with Ghost 1.0 guide
• [x] remove remote authentication configuration option in our docs/wiki
• [x] ?formats query param
• [x] update ghost-server.js -> change Alpha to Beta
• [x] go over LTS branch and update broken links e.g. in the content folder or readme
• [x] Update installation guide for self hoster
• [x] update storage and scheduling guides - adapter location
• [x] https://dash.readme.io/legacy/project/ghost/v1.0.0/docs/how-to-setup-ssl-for-self-hosted-ghost - what about this page? stay as is
• [x] https://dash.readme.io/legacy/project/ghost/v1.0.0/docs/how-to-setup-ssl-for-self-hosted-ghost - what about this page? stay as is
• [x] https://docs.ghost.org/docs/troubleshooting-guide

@kevinansfield

• [x] cleanup wiki pages
• [x] document grunt master
• [x] yarn run init -> explain that this command is only for initial setup + warning on feature branches!
• [x] grunt file: go over documentation and double check if we have old documentation for 1.0 for old commands
• [x] grunt dev documentation to explain when/why to use the individual commands
• [x] Add client documentation for developing
• [x] https://www.google.co.uk/search?client=safari&rls=en&q=site:support.ghost.org&ie=UTF-8&oe=UTF-8&gfe_rd=cr&ei=YOgrWdioG-_GXqvOvvgO - replace and then redirect the old content (the new content should live on another readme.io site)
• [x] Update README master + remove alpha wording
• [x] Update contributing guide master
• [x] highlight github README (GHOST PRO) section

@cobbspur

• [x] http://support.ghost.org/supported-node-versions/ - LTS vs. 1.0
• [x] documentation suggestions: https://github.com/TryGhost/Ghost/issues/8421
• [x] server logs - explain server logs and logging - support.ghost.org + wiki?
• [x] how to migrate from LTS to 1.0 - page?
• [x] https://support.ghost.org/v1-0-alpha to https://support.ghost.org/v1-0-beta?
• [x] manage alpha/beta pages on General category

@frantzypants

• [x] help.ghost.org to the list - the settings screens and anything with the editor will need updating.

soon

• [x] rework main contributing guide
• [x] Where is says {{#if image}}, it should be {{#if feature_image}}.
  Instead of should be - https://themes.ghost.org/docs/if
• [x] https://ghost.slack.com/archives/C04CUS2R3/p1497969873979042
• [x] there are for sure old articles for https://www.ghostforbeginners.com, which is always number one in the search result in google -> I (Aileen) sent a message, to David B. -> replied that he'll start updating his posts now
• [x] document how to use env variables for config!!!!!!! look at github issue/pr's you will something useful or slack has old conversations as well
• [x] document how to debug config output
• [x] #8633
• [x] Reactivate/Rewrite using Ghost as NPM module for docs.ghost.org 1.0
• [x] https://docs.ghost.org/v1.0.0/docs/how-to-upgrade-ghost - enable this and rewrite to use the CLI
• [x] ensure that all model properties are correctly documented e.g. author.feature_image is not valid, but the theme developer must be able to lookup the valid properties in the docs
• [x] http://themes.ghost.org/docs/changelog#ghost-100-beta - update if image deprecations are fatal and add more stuff in the chanelog if needed

[kirrg001]

We have added two new wiki pages so far. Both need a final review.

https://github.com/TryGhost/Ghost/wiki/Working-with-Ghost

• this is a developer documentation
• it will be referenced in the Ghost README.md via #8175.
• we should reference the new developer documentation here as well https://github.com/TryGhost/Ghost/blob/master/.github/CONTRIBUTING.md#installation--setup-instructions.
• the documentation needs some more guidance about how to develop the client @kevinansfield

https://github.com/TryGhost/Ghost/wiki/Developer-(Local)-Install

• as soon as we release the first 1.0.0 beta version, this documentation will guide people how to install and start the Ghost 1.0.0 beta. A final review from @acburdine would be great.

[frantzypants]

Thinking we should add updating help.ghost.org to the list - the settings screens and anything with the editor will need updating.

[ErisDS]

Some notes:

alpha-and-beta-versions

• this mentions doing a release "today"
• doesn't explain the difference between alpha and beta, not really important tho

installing-ghost-via-the-cli

• missing explanation of the system stack e.g. for production the fact that MySQL and nginx are required
• this may need to cover users and permissions? Not sure if Ghost-CLI is going to handle this
• missing explanation ghost install vs ghost install local
• ghost doctor, ghost config & ghost setup are not documented
• mentions [email protected] but I'm not sure this is this a real address?

configuring ghost

• location of configuration files is different in Ghost-Cli
• still says Ghost is configured with sqlite3 by default

1-Click installer & Hosting

• IMHO this should be "Hosting" with an explanation of the supported stack (see https://github.com/TryGhost/Ghost-CLI/wiki/System-Stack) & where to get a suitable server. Any mention of 1-click installers or other hosts should be that it's not officially supported?

General:

• I think we need to make the new officially supported stack front-and-centre for everything to do with self-hosting
• I think we're missing a page about how to install ghost (using ghost install local if you're developing themes etc - would be really to have a theme devs guide/landing page that explains gscan and links to themes.ghost.org as well)
• I believe Ghost-CLI is likely to need its own section of extended documentation beyond the main how-to-install type guide, covering the advanced commands & what it's doing behind the scenes. I 100% approve of the new all-docs-live-at docs.ghost.org, so would strongly advocate for moving the docs at https://github.com/TryGhost/Ghost-CLI/wiki & removing the extra wiki?

_Caveat: These are opinions & I haven't read everything, just a few bits from the perspective of being a CLI user._

[kirrg001]

@ErisDS

I have added this issue back to the Ghost backlog.
Thanks for your notes 👍

We kept the CLI documentation for the first beta release short on purpose (was discussed/agreed in slack). The goal was to cover the basic CLI commands for development install. See e.g. https://docs.ghost.org/docs/basic-nginx-config-self-hosted-with-custom-domain, we added notes to share what's upcoming. As soon as we are ready for CLI production, we will extend the CLI guides.

[ErisDS]

I didn't see that page in the docs, I was only looking for information on ghost-cli, which does the nginx config for me.

That nginx config page is very confusing, as the only thing that should be done before running ghost-cli is getting rid of the default vhost (and perhaps set the client_max_body_size). If you create this nginx setup documented on this page before you run ghost-cli, then your blog will not work as there will be multiple sites listening on port 80.

What I think we ought to do, is document what ghost-cli does in terms of nginx setup - e.g. show the configuration it creates.

[ErisDS]

The goal was to cover the basic CLI commands for development install.

Quick Q to clarify what is meant by a development install? Did you mean self-hoster install here? because a development install would be ghost install local which has not yet been documented.

[kirrg001]

Oh that is interesting. It was ghost install local before 😕 I will change it back for now.

[ErisDS]

I am still not sure if there is clarity here:

ghost install local = developer install, for running on your local machine and testing. Does not setup nginx etc, uses sqlite3. Meant for quick tests or installing locally to create themes and apps.

ghost install = for production servers, only runs on linux and warns if it is not ubuntu 16.04

I don't understand why we have cli + separate nginx documentation in the same section?

If the current CLI guide is meant to just be for developers testing out locally, it doesn't fit under a section called "Self-host" & also this should be clearer. If it's meant to be the self-hosting instructions, then it should be documenting that ghost install does the nginx setup.

I know that next sprint is going to be a CLI sprint, and I understand wanting to keep it short to start with, however I'm double checking this because the documentation makes it seem like the difference between ghost install and ghost install local is not well understood.

[kirrg001]

I know that next sprint is going to be a CLI sprint

Correct.

ghost install local = developer install, for running on your local machine and testing

Yes absolutely correct. In theory, you can use ghost install local in your droplet, configure the rest yourself (e.g. nginx) and you can test the beta. But sure, it was designed for local install.

---

I absolutely agree having this section under Self Hosters might be a big confusion, but that's why we have put warnings everywhere. I can't remember that we have gotten feedback that the guide is very bad/confusing, but i might be wrong.

We all knew that the CLI was and is not ready yet and we all knew that the the next sprint is going to be a pure CLI sprint pulling it straight. Let's tackle this together 😎

[PaszaVonPomiot]

Hi, have you considered adding a section for self-hosters with non-standard stack? I could provide some key information for RedHat/Centos users regarding firewall, selinux and nginx settings.

[ErisDS]

This would defeat the point of having an "official" stack.

What we are trying to achieve is not having the core team spending large amounts of time trying to add support for every possible self-hoster setup & adding a ridiculous QA overhead that literally stops us from being able to do anything ever. Instead, we have one stack that we support for self-hosters and that is Ubuntu 16.04 + MySQL + Nginx + Systemd.

You are more than welcome to ignore the official recommendation, but in that case you would need to refer to community documentation not official documentation.

[PaszaVonPomiot]

@ErisDS yes I understand the point with official stack and i fully agree with that aproach. I wouldn't want you guys to spend your time on documenting or developing for hundreds of possible builds. What I ment is to actually host or indicate (link from ghost.org) place where community could keep such documentation so that it's kept in one place. That's just an idea anyway.

[kirrg001]

All of the tasks here were resolved. We can re-open this issue if we discover any missing tasks or raise a new one 👍 Closing.