improve seo docs (#43)

browse/search.qmd

@@ -16,9 +16,11 @@ The search bar includes a drop-down button for accessing advanced search fields.
 
 ![Search results for 'exports:toJSON'](../img/search-exportsToJson.png){group="search" fig-alt="Search results for 'exports:tojson'"}
 
-## How is the package-rank score calculated?
+## How is the package-rank score calculated? {#rank}
 
-The exact algorithm is a work-in-progress and will change. 
+The rank of a package in search results is based on its [match](https://github.com/r-universe-org/cranlike-server/blob/master/src/db.js#L63-L93) with the search queries, and on its popularity/quality.
+
+The exact algorithm for calculating popularity/quality is a work-in-progress and will change. 
 At the time of writing it includes:
 
  - Number of dependents (that is to say, recursive reverse dependencies);
@@ -28,6 +30,16 @@ At the time of writing it includes:
  - Downloads per month from CRAN or Bioconductor mirrors;
  - Number of files on GitHub that mention 'library(pkgname)'.
 
+You can browse [scores and metrics for all packages](https://r-universe.dev/packages).
+
+We plan to keep updating the algorithm as R-universe matures and better data becomes available.
+
+As a package maintainer, you can [optimize your package's metadata](#keywords) and work on [improving its rank](#better-rank).
+
+## Why is a package sometimes listed twice?
+
+If a source package fails to build (which means something is very wrong) then you see a red “build failure” message.
+If there was a previous successful build, it is kept there as well for users to install.
 You can explore [scores and metrics for all packages](https://r-universe.dev/packages).  
 The algorithm will evolve as R-universe matures and better data becomes available.
 

publish/metadata.qmd

@@ -12,9 +12,9 @@ The first step towards making your package easier to find by search is to polish
 - Details;
 - URL by adding the R-universe URL. [Example](https://github.com/r-lib/gert/blob/e5030397517a8658ade1d82a6edd788cf7e935da/DESCRIPTION#L16-L17)
 
-### How to add keyword labels to an R package?
+### How to add keyword labels to an R package? {#keywords}
 
-R-universe's search algorithm uses keywords associated with a package.
+R-universe's [search algorithm](#rank) uses keywords associated with a package.
 
 If the R package is hosted on GitHub you can add keywords by configuring [repository topics](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). 
 
@@ -23,8 +23,9 @@ This field [is permitted on CRAN](https://cs.github.com/?q=org%3Acran+X-schema.o
 
 The build system may also add some keywords automatically based on analysis of the package, including the names of system libraries that the package links to, or language tags like `c++` or `openmp`.
 
-### How to increase the rank of a package?
+### How to increase the rank of a package? {#better-rank}
 
+The place of your package in search results depends on its [rank](#rank).
 One aspect might be to get more GitHub stars.
 Read about ideas in the blog post ["Marketing Ideas For Your Package"](https://ropensci.org/blog/2024/03/07/package-marketing/).