-
Notifications
You must be signed in to change notification settings - Fork 78
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #21 from sherlock-project/refresh-website
Refresh website
- Loading branch information
Showing
33 changed files
with
1,341 additions
and
172 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,32 @@ | ||
# [Sherlock](http://sherlock-project.github.io) website | ||
# Mintlify Starter Kit | ||
|
||
<p align="center"> | ||
<img src="assets/img/sherlock-project.svg"> | ||
</p> | ||
Click on `Use this template` to copy the Mintlify starter kit. The starter kit contains examples including | ||
|
||
- Guide pages | ||
- Navigation | ||
- Customizations | ||
- API Reference pages | ||
- Use of popular components | ||
|
||
### Development | ||
|
||
Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command | ||
|
||
``` | ||
npm i -g mintlify | ||
``` | ||
|
||
Run the following command at the root of your documentation (where mint.json is) | ||
|
||
``` | ||
mintlify dev | ||
``` | ||
|
||
### Publishing Changes | ||
|
||
Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard. | ||
|
||
#### Troubleshooting | ||
|
||
- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies. | ||
- Page loads as a 404 - Make sure you are running in a folder with `mint.json` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
--- | ||
title: 'Adding sites' | ||
description: '' | ||
--- | ||
|
||
## Site Analysis | ||
|
||
To add sites to Sherlock is relatively straight forward. But, there is some background that will help | ||
you in your task. | ||
|
||
Sherlock relies on the site's designers providing a unique URL for a registered username. To determine | ||
if a username is available, Sherlock queries that URL, and uses to response to understand if there is | ||
a claimed username already there. | ||
|
||
The [data.json](https://github.com/sherlock-project/sherlock/blob/master/sherlock/resources/data.json) file contains all of the | ||
information about which sites Sherlock will query usernames for, and how that query should be | ||
carried out. | ||
|
||
Here is an illustrative entry for one site in the | ||
[data.json](https://github.com/TheYahya/sherlock/blob/master/data.json) file. Following this, is a | ||
more detailed description of each entry. | ||
|
||
```json | ||
"Some Cool Site That Everyone Loves": { | ||
"errorType": "status_code", | ||
"regexCheck": "^[a-zA-Z][a-zA-Z0-9_-]*$", | ||
"url": "https://somecoolsitethateveryoneloves.com/members/{}", | ||
"urlMain": "https://somecoolsitethateveryoneloves.com", | ||
"username_claimed": "blue", | ||
"username_unclaimed": "noonewouldeverusethis7" | ||
}, | ||
``` | ||
|
||
- **errorType** | ||
|
||
Required field that defines the detection method. | ||
See the Detection Algorithms section below for more details about the options here. | ||
|
||
- **regexCheck** | ||
|
||
Optional field that specifies a regular expression that only matches on a valid username. | ||
This is used to flag usernames that may not be allowable on a given site. Note that | ||
a username that is valid on one site may not be allowed on another site. | ||
- **url** | ||
|
||
Required field that defines the format of a member's URL on the site. | ||
Use the curly brackets (i.e. "{}") to record where the username appears in the URL. | ||
- **urlMain** | ||
|
||
Required field that defines the site's URL. | ||
- **username_claimed** | ||
|
||
Optional field that defines a username that is claimed. This is used for tests. | ||
Note that even though this field is optional for Sherlock functionality, the tests | ||
will fail if a proper value is not supplied. | ||
- **username_unclaimed** | ||
|
||
Optional field that defines a username that has not been claimed. This is used for tests. | ||
Note that even though this field is optional for Sherlock functionality, the tests | ||
will fail if a proper value is not supplied. | ||
|
||
- **urlProbe** | ||
|
||
Optional field that defines a special URL which should be used to determine if a username is supported (this is normally an API call). If this is not given, then **url** will be used to check for the existence of a username. This field is useful if detecting the username using **url** is not reliable. Note that only unauthenticated API calls are supported. | ||
|
||
## Detection Algorithms | ||
With the large variety of websites, there are many different ways that detection of the availability of a username can go off the rails. So, it is important when a new site is added to configure the detection as robustly as possible. Likewise, it is crucial that tests are written for the site so that we can understand if the detection starts failing for certain sites. | ||
|
||
There are three detection algorithms supported at the current time. | ||
### HTTP Status | ||
This is the most reliably detection method. In this detection method, Sherlock does a request of the specific site URL which should exist if the desired username has been taken. If the username is unclaimed, then the site returns an HTTP Status code (typically a [404 Not Found](https://en.wikipedia.org/wiki/HTTP_404)). | ||
|
||
This is by far the most reliable method to detect if a username is available or not. Unfortunately, it is not supported by all sites. | ||
|
||
Here are some examples of what a site using this detection method would be configured: | ||
* Claimed: https://buzzfeed.com/blue | ||
* Unclaimed: https://buzzfeed.com/noonewouldeverusethis77 | ||
|
||
Site JSON Data | ||
```json | ||
"BuzzFeed": { | ||
"errorType": "status_code", | ||
"url": "https://buzzfeed.com/{}", | ||
"urlMain": "https://buzzfeed.com/", | ||
"username_claimed": "blue", | ||
"username_unclaimed": "noonewouldeverusethis77" | ||
} | ||
``` | ||
|
||
### Error Message | ||
This is the least reliable detection method. In this detection method, Sherlock does a request of the specific site URL which should exist if the desired username has been taken. If the username is unclaimed, then the site does not return any discernible HTTP Status code. Sites with this design will display some error message, or perhaps directly offer the user a chance to sign-up for the site. | ||
|
||
For this detection method, Sherlock looks for specific error text. Since the error message might change with minor updates on the site, this mechanism is the most fragile. | ||
|
||
Here are some examples of what a site using this detection method would be configured: | ||
* Claimed: https://blue.basecamphq.com | ||
* Unclaimed: https://noonewouldeverusethis7.basecamphq.com | ||
|
||
Site JSON Data | ||
```json | ||
"Basecamp": { | ||
"errorMsg": "The account you were looking for doesn't exist", | ||
"errorType": "message", | ||
"url": "https://{}.basecamphq.com", | ||
"urlMain": "https://basecamp.com/", | ||
"username_claimed": "blue", | ||
"username_unclaimed": "noonewouldeverusethis7" | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
--- | ||
title: 'Create Plant' | ||
openapi: 'POST /plants' | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
--- | ||
title: 'Delete Plant' | ||
openapi: 'DELETE /plants/{id}' | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
--- | ||
title: 'Get Plants' | ||
openapi: 'GET /plants' | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
--- | ||
title: 'Introduction' | ||
description: 'Example section for showcasing API endpoints' | ||
--- | ||
|
||
<Note> | ||
If you're not looking to build API reference documentation, you can delete | ||
this section by removing the api-reference folder. | ||
</Note> | ||
|
||
## Welcome | ||
|
||
There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification. | ||
|
||
<Card | ||
title="Plant Store Endpoints" | ||
icon="leaf" | ||
href="https://github.com/mintlify/starter/blob/main/api-reference/openapi.json" | ||
> | ||
View the OpenAPI specification file | ||
</Card> | ||
|
||
## Authentication | ||
|
||
All API endpoints are authenticated using Bearer tokens and picked up from the specification file. | ||
|
||
```json | ||
"security": [ | ||
{ | ||
"bearerAuth": [] | ||
} | ||
] | ||
``` |
Oops, something went wrong.