How To Submit Your Focus
In our Share Your Focus piece we launched the Focus Template Repository, allowing you to make your creations publicly accessible through GitHub. This article takes you through all the steps you need to undertake to do just that, from creation to submission; so if you’re looking for a comprehensive guide, you’re in the right place.
On Mojeek
1. Use Focus
The first thing to do is to familiarise yourself with the tool. If you’ve already used the it for a while, and you’ve created something that you think is a great candidate for the Open Source Repo, then please skip ahead to step 4. Focus allows you to create lists of sites to be included and/or excluded when making searches on Mojeek, meaning it is a very useful tool when it comes to searches within specific and defined categories – this being said, if you’ve found another use for it then we’re always very interested in hearing it, get in touch.
To start you should have a quick scan of the Focus landing page, which quickly and visually takes you through the process of creation and refinement, before heading over to your Dashboard to see what you might be able to do with it.
On the right-hand side are Settings, which determine if widgets appear on search results pages, and if quick search options appear in the search bar. You can also use this panel to tweak clustering when using Focus (by default clustering is off), but for the moment we’ll leave that option out, as it will only affect your results.
For the next step (creation) it is likely going to be easier if you enable both of these options, but you can keep the Dashboard open or return to it regularly in order to amend your creations as you go. At the bottom of the page you can see the section into which templates submitted to and accepted by the Repo sit. Both Education and TechNews here were submitted by Mojeek users.
Let’s scroll back up and click “Create new” to learn about how to make a Focus using this console.
2. Create and Test
Any good Focus will start with an idea, and so it’s best to come to this process with one in mind. As mentioned before, this works well with specific category searches, groupings of websites which make sense together as they have some kind of thematic loop running through them. Focus can also be used to, say, not have Amazon and other retailers which you don’t agree with the business practices of in shopping results, but this is not really what it is made for. Your mileage may vary if using it to just remove things.
Once you have your idea, it’s now time to give it a name and start listing the websites which would go into the perfect search for that idea. The name goes into the Name box and the Sites to Search will go below that. Pay attention to the character restraints for the top box and the site limit (25) for the second.
One important consideration here is that using a “.” or not will change what is being searched across when it comes to subdomains:
- .example.com will include www.example.com, blog.example.com, and newsletter.example.com as all subdomains are included in this Focus, whereas
- example.com will only search across www.example.com when using the Focus.
This distinction is good to understand, and if you’d like to use some of example.com’s subdomains but not others, you can either single them out in the Sites to Search, or put specific subdomains in the Exceptions box to ensure that they are excluded.
After filling all the relevant boxes you can now click Save which will return you to your Dashboard with a new Focus now present.
If you click the down arrow next to that Focus you can now use it, and that is the next step in our process. Stress test this creation and think about how it could be better by putting a query into that box.
Alternatively, and this is why the search bar option was suggested in step 1, you can click the buttons which pop up in the search bar on the home and results pages to switch over to using a Focus.
3. Amend
Perform some searches and see how the Focus is working. Are there obvious changes that should be made? Additions? Exclusions? Should you go back to the drawing board? Edits can be made from the results pages if you have turned on the widgets, or you can return to the Dashboard and amend your creations using the edit function.
Once you’ve put your Focus through its paces and are confident that it does what you intended, or at least something which would be useful to share with others, the harder part of this is done. Now it’s time to head to GitHub and get submitting. Luckily this guide covers all of those steps as well!
On GitHub
4. Using GitHub
GitHub is a developer platform which allows you to create, store, and manage code. When that code is put up publicly, it also allows you to raise issues and make amendments on others' code, creating an open ecosystem of code contributions.
It should be noted here that GitHub is a owned by Microsoft, and so you should take the privacy precautions that you would normally with a tool like this. Here we have chosen to put up the Focus Templates on GitHub as it is the most-widely used tool of its kind; this being said, if enough people requested that we mirror this elsewhere (on GitLab, Codeberg etc.) then we’d definitely consider it.
Your first step with GitHub is to get yourself an account, which requires an email address.
Once you’ve confirmed your email and created a suitable handle, head over to the Open Source Focus Repo whilst also having your Dashboard ready. Step 5 will outline some of the other checks but just make sure through the Issues and Pull Requests that there isn’t already a sitting request for the addition of something very similar. If yours is near-enough unique then we can proceed.
5. Focus Submission Format and Guidelines
If you click Backup this Focus on any of your creations you’ll see something resembling this:
{"SmallWeb":"i=.neocities.org,.carrd.co,.mmm.page,.omg.lol,.smol.pub,.bearblog.dev,.posthaven.com,.leprd.space"}
Where the first part is the name, followed by your i= inclusions and your e= exclusions. A .focus file is not dissimilar, let’s take a look at the makeup of one of these files – this is presented to you as a checklist if/when you create an Issue:
If there were any exclusions then they would show up below the i= inclusions as another part of the file. The Contributing Guide gives you a full rundown of best practice when it comes to submitting, outlining what is likely to be accepted and what is not. The things which you likely don’t have yet here are a description and an icon. For the description please keep it as short as possible so that it’ll sit neatly on the page; for the icon we suggest going to svgrepo and finding a commercial-friendly and royalty-free option.
6. Issue or Pull Request
For those who understand how to pull and amend a repo locally and then create a Pull Request from it, we appreciate how easy this makes it for us. Please feel free to fork the repository and we’ll inspect the resulting code once it’s done. For those who aren’t so comfortable with this level of involvement with code, you can use the Issue Template which has been created specifically for you, just click New issue and then Submit Focus Template:
The Issue: Submit Focus Template screen contains a few fields that you’ll need to edit. Firstly use the Add a title field to inform us that you are submitting a Focus and its name; then go through the other fields in the Add a description box to give us all the information needed to reconstruct your creation. Here the italics are what you need to replace in that box:
- title: your title
- description: your description
- author: your name or handle
- icon: a link to the svgrepo icon you’ve selected, or an svg from elsewhere
- Replace this text with your i= and e=, one per line - delete this and insert in your i= inclusions and e= exclusions, one per line
Once you’ve filled all of that out, hit Submit new issue and one of us will be pinged that there is something new to look at. Hopefully your Template will soon end up on Mojeek itself. It will be checked up against the guidelines as well as tested for functionality. With previous additions title or description amendments have been suggested in order to make the Focus look better when it makes it to the Template Library. At all stages you’ll be asked for your thoughts before these things get edited, so keep your eyes on your email inbox or GitHub.
If any of these steps have seemed confusing to you, or you need any further assistance in the process of creating a Focus don’t hesitate to contact us via the Contact Page or the Community.
