How can contributors build an algolia search index?

I have a test algoilia site, i've set the instance id, admin api key, but the index is never populated.

Add a link to each GitHub hosted page, which opens the current page in GitHub.

Todos:

• 🎨design spec → @peterzimon
• Implementation incl. correct redirect link to GitHub
• Design iteration

Issue Summary

I'm getting an 404 error at " https://docs.ghost.org/api/handlebars-themes/helpers/blog/ "

seems like the '@blog' helper is only found through the sidebar and not through the date helpers page...https://docs.ghost.org/api/handlebars-themes/helpers/data/

I guess it needs to be switched out for the '@site'

To Reproduce

Go to: https://docs.ghost.org/api/handlebars-themes/helpers/data/

you'll see that '@blog' isn't listed on this page but only listed in the sidebar.

Allow Ghost docs to be searched directly from Chrome with Google Omnibox (eg. In the address bar type youtube.com then press tab to search YouTube)

Basic info:
https://stackoverflow.com/questions/7630144/how-to-add-google-chrome-omnibox-search-support-for-your-site

Now that we have rebuild webhooks, it'd be interesting to add a Tutorial explaining how to build a static site that auto updates on Ghost content updates. I'd love to help on this if you can point me in the right direction :)

At the moment, there's no way to order posts within channels or collections or get-helper lists, so that featured posts are first. This is a super common request. Instead, it requires use of the get helper, which breaks pagination, and in many use-cases still doesn't do quite the right thing.

Ideally, we want to make this possible at the API level, by changing the order query parameter.

This is already possible with the order parameter, it's just undocumented.

Url encoded form: https://demo.ghost.io/ghost/api/v2/content/posts/?key=22444f78447824223cefc48062&fields=title,featured,published_at&order=featured%20desc,published_at%20desc

Routes/get helper, etc form: order: “featured desc, published_at desc”

The current e2e test is covering almost all important parts already, but can be improved to include the testing of the TOC scroll behaviour.

Furthermore, we should implement continuous integration for the e2e test.

Todos:

• implement TOC scroll behaviour test
• implement continuous integration

I am working on the Integrations page for Google Sheets + Ghost, explaining how to embed a spreadsheet into a Ghost post. This is great for people who want to embed dynamic data or swipe files that their readers can export from their site.

When I published the page, the embed appears very small on the page:

This is not a usable working example of this embed and should fit to the width of the content. Can we fix this?

The embed code used is:

<iframe src="https://docs.google.com/spreadsheets/d/e/2PACX-1vQKQwfka4cgU7mnS2uAiCMKs0wkmHJQdH5sc4mp231iVKjwueBVaX3Qy8no7gTihQXr6kwJ52TLyfLt/pubhtml?widget=true&amp;headers=false"></iframe>

Note: I've unpublished the Integrations page for now, but the content is in draft in Ghost Admin.

Refactor and tidy up CSS.

Issue Summary

In Docs

https://api.ghost.org/docs/overview

there is sentence

For more information on how this works please see the Client Authentication section, or the ghost.url.api() docs in themes.

with links to

https://api.ghost.org/v0.1/docs/client-authentication

and

http://themes.ghost.org/v1.0.0/docs/ghost-url-api

First one is redirected to

https://api.ghost.org/docs/client-authentication

The second giver error page

404
You just hit a route that doesn't exist... the sadness.

Docs Home
Ghost.org

Please add in this issue info how to create pull requests to docs because of docs do not mention about it.

I read the document of storage adapter and find Tencent Cloud COS is not listed in "Available custom storage adapters". I've written an adapter(https://github.com/zkd8907/ghost-qcloud-cos-store) for Tencent Yun. May I make a pull request and add it to the docs?

https://docs.ghost.org/api/webhooks/ only lists 3 events rather than the full list of events that were added in Ghost 2.16.0.

I wonder if we should document the webhook payload format too?

Full list of events:

Global
'site.changed' - Site changed (rebuild)

Posts
'post.added' - Post created
'post.deleted' - Post deleted
'post.edited' - Post updated
'post.published' - Post published
'post.published.edited' - Published post updated
'post.unpublished' - Post unpublished
'post.tag.attached' - Tag added to post
'post.tag.detached' - Tag removed from post

Pages
'page.added' - Page created
'page.deleted' - Page deleted
'page.edited' - Page updated
'page.published' - Page published
'page.published.edited' - Published page updated
'page.unpublished' - Page unpublished
'page.tag.attached' - Tag added to page
'page.tag.detached' - Tag removed from page

Tags
'tag.added' - Tag created
'tag.edited' - Tag updated
'tag.deleted' - Tag deleted

Subscribers
'subscriber.added' - Subscriber added
'subscriber.deleted' - Subscriber deleted

Issue Summary

Trying to answer this forum topic I went looking for the info about template overrides but at first I thought it had been removed. I did eventually find a couple of references to overrides on the subscribers theme doc but they were well hidden and assumed knowledge about where to find the default templates.

Issue Summary

In the Troubleshooting section of the migration API docs there are two code samples shown but it looks like these should be images?

To Reproduce

1. Open https://docs.ghost.org/api/migration/#troubleshooting

Issue Summary

Integrations with descriptions that wrap end up with odd text alignment.

To Reproduce

1. Open the homepage, look at the Google Analytics integration icon

Tested in latest Safari and Chrome

Issue Summary

After Gatsby responsive images have been added to Ghost Docs the vertical rhythm is not applied to images anymore. The reason is that until now images have been wrapped in a <figure> tag, but since resp. images they are wrapped in a <p> tag.

This repository is only concerned with Ghost Documentation. If you're having trouble with Ghost itself, please use: https://forum.ghost.org 👫

Issue Summary

In the code that you copy and paste from https://docs.ghost.org/integrations/disqus/ it appears that line 5 is missing a ; . I could not find this page anywhere otherwise I would have submitted a pull request.

To Reproduce

Explain how someone else can reproduce the issue and see it for themselves

1. Go to https://docs.ghost.org/integrations/disqus/

Any other info e.g. Why do you consider this to be a bug? What did you expect to happen instead?

When using the code as is disqus will not load. After looking at the code from https://utekblog.disqus.com/admin/install/platforms/universalcode I noticed the semi colon. Once I added that things worked as expected.

Hi,

Need help in resolving this error.

Followed all these steps

1. git clone this repo & cd into it as usual
2. npm install --global gatsby-cli to install Gatsby
3. yarn to install top-level dependencies.
4. Copy .env.example to .env.development

gatsby develop : No Issues
gatsby build: Getting error

error We encountered an error while trying to load your site's gatsby-config. Please fix the error and try again.


  Error: GHOST_API_URL and GHOST_API_KEY are required to build. Check the CONTRIBUTING guide.

Not sure what i am missing here!
Looking for help to resolve this issue.

Other details:
➜ node -v
v11.6.0
➜ npm -v
6.5.0
➜ gatsby -v
2.4.8

Thanks in advance.

This seems to happen only after a fresh build and on the first load. A forced refresh fixes this situation temporary.

I've spotted this issue a few times when using search. Sometimes I click on a search result, and it populates the search box rather than taking me to the page. I thought it was random, but I think I have a reproduction case.

To Reproduce

1. Navigate to a section of the Ghost CLI Knowledgebase, for example "Folder stucture"
2. Search for something that also exists on this page, for example "second domain"
3. Click on the "Knowledgebase" entry
4. See that the search box is updated, but not closed

Now that I understand the reproduction case, I can see that the anchor in the URL is updated. Therefore I think the bug is actually that the modal doesn't close if only the anchor changes.

The GCS adapter thombuchi/ghost-google-cloud-storage is unmaintained and apparently does not work with the latest Ghost version.

There is a fork KaySchneider/ghost-google-cloud-storage which is more recently updated, perhaps the maintainer would be willing to make this the "official" one?

Either way, the link to the unmaintained adapter should be removed or marked as obsolete.

In current structure our Gatsby files are structured by API method inside of the /gatsby folder.
The original gatsby-node and gatsby-browser files only function as index files for the API methods.

This is not very readable and should be improved, so it's possible to on a glance which fn are within those methods.

It would be optimal, if we'd had some unit tests for some components.

I Looked into Jest unit testing for a bit, but that needs some more research, as those tests are not shallow by default and need a lot of mocking.

Issue Summary

Ghost Docs is growing. In order to be able to have a consistent (mostly typographic) style throughout the site, it's necessary to have a short style guide.

We're currently using our own Tags helper component, which was a workaround until we're able to use the tags helper from the Ghost-SDK.

The gatsby-starter-ghost shows here and here how the implementation for this is done.

Todos:

• implement tags helper where applicable
• remove existing Tags component

Based on 1) experience of cloudflares page rules guide and 2) John asking whether multi-wildcard was supported in Ghost and 3) planning an update to our redirects feature and not finding all the features documented, I would like to propose some changes to the redirects guide.

I'm starting by proposing problems 😬

Issues I think exist:

1. "regex" could be considered a bit vague (there are different flavours)
2. there's no clarity around double escaping (I still am not sure myself what the rules are)
3. We don't make it clear that "multi wildcard" is supported E.g. you can use $1, $2
4. Case insensitive matching with the i flag is not mentioned
5. It's not clear that temporary redirects are the default
6. Text around the required JSON format could be more explicit
7. Minor Typo: the from field text has an additional word "you"

Possible solutions?

I think there are a couple of small changes that could be made to the text to resolve these things. E.g. using more explicit technical language in a summary somewhere like:

"The from and to fields work exactly the same as javascript's replace function, with full support for regex patterns, the i case insensitivity flag, and multiple matches using $1, $2. "

and also including the phrase "The file must be valid JSON", with the words "valid JSON" being a link to https://jsonlint.com/ (This linter gives clarity on why a file is not uploading). I think some of the text about how JSON works could also be removed or grouped together.

I would also like to propose that we include one advanced example. I'm happy to be shot down for this, but I think a lot of us like to see a super complex example to see what we can achieve (thinking about the trouble with the page rules guide)

My proposed advanced example is similar to our docs redirect, but we could probably find a better one:

{
   "from": "^/(v.*?)/docs/([a-z0-9_\-]+)(\\/)?$/i",
    "to": "/$1/$2/"
}

It includes: advanced pattern matching in JS, the need for double-escaping when using regex, 2 wildcards and the i flag all in one fell swoop, but note that I'm not really sure where and when I need to use a double backslash escape here.

It maybe that all this is waaaay to technical for the 90%. My main suggestion is really to either use more explicit language to be clearer what does and doesn't work e.g. say "valid JSON" and "javascript regex" and let people use the rest of the internet to determine what those phrases mean.

Happy to have a stab at a PR for this if folks agree.

I want to integrate with depreciated API v0.1 and make CREATE / UPDATE / DELETE operations.

Documentation about authentication is there

https://api.ghost.org/docs/user-authentication

It is enumerated some values that I should know before creating Bearer Token.

• user email
• user password
• client id
• client secret

I know my user email and password, but in admin panel (ghost v2) I can't find a place where client data are displayed.

I found table clients in the database, but It should be documented, how to find client_id and client_secret because of mapping between these names and database columns names are not obvious.

After logging to the database and typing desc clients i can see:

+-----------------+---------------+------+-----+-------------+-------+
| Field           | Type          | Null | Key | Default     | Extra |
+-----------------+---------------+------+-----+-------------+-------+
| id              | varchar(24)   | NO   | PRI | NULL        |       |
| uuid            | varchar(36)   | NO   |     | NULL        |       |
| name            | varchar(50)   | NO   | UNI | NULL        |       |
| slug            | varchar(50)   | NO   | UNI | NULL        |       |
| secret          | varchar(191)  | NO   |     | NULL        |       |
| redirection_uri | varchar(2000) | YES  |     | NULL        |       |
| client_uri      | varchar(2000) | YES  |     | NULL        |       |
| auth_uri        | varchar(2000) | YES  |     | NULL        |       |
| logo            | varchar(2000) | YES  |     | NULL        |       |
| status          | varchar(50)   | NO   |     | development |       |
| type            | varchar(50)   | NO   |     | ua          |       |
| description     | varchar(2000) | YES  |     | NULL        |       |
| created_at      | datetime      | NO   |     | NULL        |       |
| created_by      | varchar(24)   | NO   |     | NULL        |       |
| updated_at      | datetime      | YES  |     | NULL        |       |
| updated_by      | varchar(24)   | YES  |     | NULL        |       |
+-----------------+---------------+------+-----+-------------+-------+

But with client_id with value id and uuid and cleint_secret with value secret I can't get token and see the response:

401

{"errors":[{"message":"Access denied.","context":"Client credentials were not valid","errorType":"UnauthorizedError"}]}

My question is? It is possible to add a view of client_id and client_secreat in admin? Or type docs about a manner of obtaining these values.

To enable horizontal scrolling for tables that are rendered from a Ghost post source, we need to add a <div> wrapper for those <table> elements, due to a flexbox bug.

The probably easiest way to do so, is to use the gatsby-browser API.

Todos:

• design spec → @peterzimon
• implementation

Problem description

The currently implemented solution to generate the sidebar navigation from yaml files reads all yaml files from within a /src//data/sidebars directory, which is weird because those files are part of the content and not the code and currently stored away from the content files.

Those sidebar files should actually live right where they belong: in the related content folder.

Proposal

Refactor the sidebars components to be more automatic and generic and read them from the content directories.

Create this new implementation as plugin, so it can be reused.

Todos

• move all sidebar files out of /src into their associated content dir
• create a plugin that finds those files and can be simply used as Sidebar component

Switch on Integrations index in global search, which is currently disabled for the global search.

👉 https://github.com/TryGhost/docs/blob/master/src/components/common/search/Search.js#L135

Issue Summary

After landing on the 404 page it's not possible to use any of the links to get away from the 404 page.

To Reproduce

1. Open a non-existant URL, I hit when I noticed the problem https://docs.ghost.org/integrations/comments?no-cache=1
2. Try clicking on any docs link and nothing will happen
3. Note there are errors in the dev tools console

Add a no-script fallback to improve site performance.

This is accomplished by adding a script to the gatsby-ssr.js as used here

Problem 1:
Docs are not clear at all about what permissions the token integrations have vs the User Authentication method.

Problem 2:
The URL in the creating a session is wrong. It says POST /sessions/ but it's actually /admin/session/ (especially note the ending s)

Problem 3:
The /session/ endpoint requires an Origin or Referrer but doesn't mention it in the docs, otherwise you get the error: 'Could not determine origin of request. Please ensure an Origin or Referrer header is present.'

Problem 4:
The body of the creating a post is wrong. It uses the key post when it's actually posts

It's very frustrating when you have to constantly second guess the docs!