{"id":14108869,"url":"https://github.com/mlbrgl/ghost-algolia","last_synced_at":"2025-08-01T07:33:04.667Z","repository":{"id":52468178,"uuid":"97222802","full_name":"mlbrgl/ghost-algolia","owner":"mlbrgl","description":"Provides integration between Ghost (CMS) and Algolia (Search as a Service)","archived":true,"fork":false,"pushed_at":"2021-04-28T07:43:25.000Z","size":177,"stargazers_count":59,"open_issues_count":0,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-05-14T04:43:18.992Z","etag":null,"topics":["algolia","ghost"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlbrgl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-14T10:33:30.000Z","updated_at":"2023-01-28T09:17:48.000Z","dependencies_parsed_at":"2022-08-18T23:10:45.424Z","dependency_job_id":null,"html_url":"https://github.com/mlbrgl/ghost-algolia","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlbrgl%2Fghost-algolia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlbrgl%2Fghost-algolia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlbrgl%2Fghost-algolia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlbrgl%2Fghost-algolia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlbrgl","download_url":"https://codeload.github.com/mlbrgl/ghost-algolia/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228351542,"owners_count":17906500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algolia","ghost"],"created_at":"2024-08-14T10:01:52.375Z","updated_at":"2024-12-05T18:30:30.848Z","avatar_url":"https://github.com/mlbrgl.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Community Integrations"],"sub_categories":[],"readme":"_Apr 2021: archiving as I am not planning on working on this in the foreseeable future._\n\n---\n\n# Ghost / Algolia integration\n\nEnables [Ghost](https://ghost.org) sites owners to index their content through [Algolia](https://www.algolia.com).\n\n:radioactive: :mushroom: **The master branch does not contain production-ready code at that stage. Please use the released versions instead.**\n\n# What it does\n\nWhen you work on a story, and publish it, the content of that story is sent to Algolia's indexing engine. Any change you make to that story or its state afterwards (updating content, deleting the story or unpublishing it) is automatically synchronised with your index.\n\n## Fragment indexing\n\nFragment indexing refers to breaking up an HTML document into smaller blocks (or fragments) before sending them to the indexing engine. Those fragments are generally composed of a heading (h1, h2, ...) and some text. You may read about the rationale behind fragment indexing on the [KirbyAlgolia project page](https://github.com/mlbrgl/kirby-algolia#kirby--algolia-integration).\n\nHere is how the fragmenting engine handles the different types of fragments, in terms of when the indexing events are fired:\n\n```\nline\nline\n--\u003e INDEXING (headless fragment)\n# heading\nline\n--\u003e INDEXING\n## heading\n--\u003e INDEXING (content-less heading)\n### subheading\nline\nline\n--\u003e INDEXING\n# unlikely heading\n--\u003e INDEXING by code convenience but very little value\n```\n\n## Structure of a fragment\n\n- `objectID`: automatically generated by Algolia (e.g. 565098020)\n- `post_uuid`: automatically generated by Ghost (e.g. 8693c79d-7880-4e17-903d-7afd448e3517)\n- `heading`: the heading of the fragment being indexed (e.g. My first paragraph)\n- `id`: the ID of the fragment being indexed (e.g. my-new-blog-post#card-markdown--My-first-paragraph--1)\n- `importance`: an integer reprensenting how deep in the article structure a fragment is located (e.g. 1). The deeper the less relevant.\n- `post_title`: the title of the post being indexed (e.g. My new blog post)\n- `post_published_at`: the published date of the post (e.g. 2017-09-03T19:14:03.000Z)\n- `content`: the content of the fragment being indexed (e.g. The content of the first paragraph)\n\n# What it does not do\n\nThis app only deals with the indexing side of things. Adding the actual search widget is not part of the scope at this point. A good option to look into is [InstantSearch.js](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/).\n\n# Installation\n\n1. Create free accounts on both [Github](https://github.com/) and [Netlify](https://www.netlify.com/).\n\n2. Configure Algolia's index\n\nCreate a new API key on Algolia's dashboard. You want to make sure that the generated key has the following authorizations on your index:\n- Search (search)\n- Add records (addObject)\n- Delete records (deleteObject)\n\nNext add the following attributes as searcheable attributes, in the ranking tab under the \"Basic settings\" section:\n- `post_title`\n- `heading`\n- `content`\n- `post_uuid`\n\nIgnore any warnings about the attributes not being found in a sample of your records, as you should not have any records at that stage yet.\n\nFinally, add `importance` as a custom ranking attribute in the ranking tab under the \"Ranking Formula \u0026 Custom Ranking\" section. This will allow the tie-break algorithm to give preference to higher fragments in the document structure. In other words, h1 tags will rank higher than h2 tags if they otherwise have the same textual score.\n\n3. [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/mlbrgl/ghost-algolia)\n4. On Ghost's admin panel, create a new custom integration and the following webhook:\n- Name: Post published, Event: Post published, target URL: the endpoint of the post-published function, found on Netlify's admin panel (https://YOUR-SITE-ID.netlify.com/.netlify/functions/post-published)\n\n# Usage\n\n## Real-time indexing\n\nTriggering indexing is transparent once the app is installed and happens on the following ghost panel operations:\n- publishing a new post (add a new record)\n\n**Cost**: as many operations as fragments in the current post\n\n# Compatibility\n\nCheck the last release (on the [releases](https://github.com/mlbrgl/ghost-algolia/releases) page) to see what Ghost version is currently supported.\n\n# Roadmap\n\n- event: updating a published post (update an existing record)\n- event: unpublishing a post (remove a record)\n- event: deleting a post (remove a record)\n- bulk indexing\n\n# Alternative\n\nFor a similar process using Zapier: https://discourse.algolia.com/t/how-to-install-algolia-for-ghost-blogging-platform/1201/8. \nPlease check the limitations, as this might not be suitable for your use case.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlbrgl%2Fghost-algolia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlbrgl%2Fghost-algolia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlbrgl%2Fghost-algolia/lists"}