-
|
I have several related sites, which, for administrative reasons, are published as separate GitHub Pages sites. For example: Each has its own GitHub project and is automatically published on updates. Algolia reads https://xpack.github.io/robots.txt, gets the list of sitemaps, and creates an index for the whole site. The index is used in the docusaurus.config.ts of each site, with the content recommended by the documentation. If I search for terms while being in the top site, things seem more or less ok. If, while being in one sub-site, I search for terms defined in another sub-site, the resulting links are wrong, they are always prefixed with the baseUrl of the current site. For example, while being in xcdl, if I search for something in xpm, I get a link like: instead of Is there any way to configure the optional I tried to read the documentation several times, but the content is a bit too cryptic for me... :-( |
Beta Was this translation helpful? Give feedback.
Replies: 1 comment 8 replies
-
|
The code we use is entirely here: import {useCallback} from 'react';
import {isRegexpStringMatch} from '@docusaurus/theme-common';
import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
import {useAlgoliaThemeConfig} from './useAlgoliaThemeConfig';
import type {ThemeConfig} from '@docusaurus/theme-search-algolia';
function replacePathname(
pathname: string,
replaceSearchResultPathname: ThemeConfig['algolia']['replaceSearchResultPathname'],
): string {
return replaceSearchResultPathname
? pathname.replaceAll(
new RegExp(replaceSearchResultPathname.from, 'g'),
replaceSearchResultPathname.to,
)
: pathname;
}
/**
* Process the search result url from Algolia to its final form, ready to be
* navigated to or used as a link
*/
export function useSearchResultUrlProcessor(): (url: string) => string {
const {withBaseUrl} = useBaseUrlUtils();
const {
algolia: {externalUrlRegex, replaceSearchResultPathname},
} = useAlgoliaThemeConfig();
return useCallback(
(url: string) => {
const parsedURL = new URL(url);
// Algolia contains an external domain => navigate to URL
if (isRegexpStringMatch(externalUrlRegex, parsedURL.href)) {
return url;
}
// Otherwise => transform to relative URL for SPA navigation
const relativeUrl = `${parsedURL.pathname + parsedURL.hash}`;
return withBaseUrl(
replacePathname(relativeUrl, replaceSearchResultPathname),
);
},
[withBaseUrl, externalUrlRegex, replaceSearchResultPathname],
);
}
export function isRegexpStringMatch(
regexAsString?: string,
valueToTest?: string,
): boolean {
if (
typeof regexAsString === 'undefined' ||
typeof valueToTest === 'undefined'
) {
return false;
}
return new RegExp(regexAsString, 'gi').test(valueToTest);
}By default Docusaurus assumes that you index your own site, and doesn't know about other things. Note that technically Algolia allows you to index Docusaurus sites alongside any other thing (including things that are not even Docusaurus) and we can't document all these patterns, it's the responsibility of Algolia to do so. What we can do is only handle a default integration of Algolia, using the most common scenario: an index dedicate to a single Docusaurus site. If that doesn't work for your case, you can still swizzle and adjust the Algolia integration according to your needs, and eventually report back by suggestion a few options that you unlock your use-case. I believe the current options may be enough for your case: maybe when you are on site1, you could use function useNavigator({
externalUrlRegex,
}: Pick<DocSearchProps, 'externalUrlRegex'>) {
const history = useHistory();
const [navigator] = useState<DocSearchModalProps['navigator']>(() => {
return {
navigate(params) {
// Algolia results could contain URL's from other domains which cannot
// be served through history and should navigate with window.location
if (isRegexpStringMatch(externalUrlRegex, params.itemUrl)) {
window.location.href = params.itemUrl;
} else {
history.push(params.itemUrl);
}
},
};
});
return navigator;
} |
Beta Was this translation helpful? Give feedback.
-
I can only know if it makes sense if you explain your use case. What config would you use and why And what does the Algolia index contains |
Beta Was this translation helpful? Give feedback.
-
The Algolia index is the result of parsing two domains (xpack and xpack-dev-tools), each with multiple sitemaps, 27 all together (but more projects will be added). The crawler uses the following two robots.txt files: Since all sites are actually part of the xPack Project, the same index is used in all sites.
Currently all sites use the config recommended by the documentation, plus:
Why I use this multi-domain, multi-web configuration? Because it looked more natural for each project to have its own documentation in the same Git repo, with automatic rebuild and publish. Is this a stupid idea? Should I move all documentation pages under a single web site? My previous Jekyll web site used this monolitic approach, and it wasn't a joy to maintain. I thought that bringing the documentation closer to the code would be better. |
Beta Was this translation helpful? Give feedback.
-
|
@slorber, for now I updated all 27 sites to use this configuration with the If you see any problem, or have a better idea, please let me know. |
Beta Was this translation helpful? Give feedback.
-
|
If you have a large amount of sites that you want to deploy independently, it makes to me. Also makes sense to me to allow a global search across all of them to increase UX.
This should work, and is the simplest solution. But know if you are on the root site, and click a hit of the root site, it opens using regular nav in a new window. That still leads to the page you were looking for, but is not an ideal UX. It would be better to provide a custom regexp per site, that doesn't consider the current site you are on as an external URL. But it is more complex to achieve. Up to you. Note that I'm not an Algolia expert, but I feel your search hits behavior is far from ideal. There must be a way to configure algolia to "prioritize" hits from the site you are currently on. For example, I'd expect this hit to come first, considering I'm on the root website and other links are coming from subprojects:
I'm pretty sure you can configure Algolia to also show the current subproject as breadcrumb, otherwise it's very difficult to know which subproject the search hit will lead to considering it's not displayed anywhere. I mean All this is outside the scope of Docusaurus, this requires more advanced Algolia config but can't really help you more on that |
Beta Was this translation helpful? Give feedback.
-
Good point. I'll see how complicated is to generate separate regexps for each site.
I noticed some less than optimal behaviours too. I'll check the Algolia configuration to see if there is anything to do to improve it. Thank you for your help. |
Beta Was this translation helpful? Give feedback.
If you have a large amount of sites that you want to deploy independently, it makes to me.
Also makes sense to me to allow a global search across all of them to increase UX.
externalUrlRegex: 'xpack\\.github\\.io|xpack-dev-tools\\.github\\.io'This should work, and is the simplest solution.
But know if you are on the root site, and click a hit of the root site, it opens using regular nav in a new window. That still leads to the page you were looking for, but is not an ideal UX.
Same if you are on xpm and search for a …