Docs: Add client-side redirect to new docs. #30774
Conversation
|
@mrdoob For the next release
|
Great! Yeah, I was going to ask why did we need Just had a look a the new docs (finally)... They're looking pretty good! However, I think they still need a few more tweaks (which I will do for In the meantime... Now that we have a jsdocs, can you investigate if we're able to generate a |
When I understand the description of Yes, we can use JSDoc to generate such files but that requires a complete separate JSDoc template. The predefined When thinking about this: If such a LLM JSDoc template is developed, it should be a separate project since any JSDoc documentation could use it to generate LLM friendly markdown files. However, developing a new template is maybe not necessary since there is an existing project for generating markdown from JSDoc: https://github.com/jsdoc2md/jsdoc-to-markdown I've tried to convert |
|
Ah, I was searching for "jsdoc to llms.txt" but "jsdoc to markdown" makes more sense. It actually needs to be in a single file. The whole documentation with all the classes in a single People developing using cursor and windsurf can then add the file for the llm/agent: 
And yes, this would definitely be a different thing from |
|
Thinking about the jsdoc template system... Could we make it so jsdocs generate files like these? That way we could just transparently replace the current documentation without having to do any redirects... 🤔 |
|
I've never seen a JSDoc-based documentation like that since the entire linking logic of JSDoc assumes all doc pages are located in the same directory. I recommend to use the JSDoc standard instead of building a custom solution. |
I'll try to figure out a script utilizing |
|
Below is the mentioned script and also the generated file import fs from 'fs/promises';
import path from 'path';
import jsdoc2md from 'jsdoc-to-markdown';
// This script converts the API documentation from JSDoc to Markdown and writes everything
// into a single build/llms.txt output file.
build();
async function build() {
// gather all files potentially holding JS Doc
const files = [];
const config = JSON.parse( await fs.readFile( 'utils/docs/jsdoc.config.json', 'utf8' ) );
const includes = config.source.include;
const excludes = config.source.exclude;
for ( const include of includes ) {
const includeFiles = await toArray( readAllFiles( include ) ); // Replace toArray() with Array.fromAsync() when supported
// filter out excluded and non-js files
files.push( ... includeFiles.filter( function ( file ) {
for ( const exclude of excludes ) {
if ( file.startsWith( exclude ) === true || file.endsWith( '.js' ) === false ) {
return false;
}
}
return true;
} ) );
}
// create output directory if not existing
const outputDir = 'utils/llm/build';
if ( await fs.stat( outputDir ) === false ) await fs.mkdir( outputDir );
// create output path and overwrite existing file
const outputPath = path.join( outputDir, 'llms.txt' );
await fs.writeFile( outputPath, '', { encoding: 'utf8', flag: 'w' } );
// convert JSDoc to Markdown and save in output file
await generateTitle( outputPath );
await generateAPI( outputPath, files );
}
// helpers
async function generateTitle( outputPath ) {
await fs.appendFile( outputPath, '# three.js \n\n' );
await fs.appendFile( outputPath, '> JavaScript 3D Library. \n\n' );
}
async function generateAPI( outputPath, files ) {
for ( const file of files ) {
await fs.appendFile( outputPath, await jsdoc2md.render( { files: file } ) );
}
}
async function* readAllFiles( dir ) {
const files = await fs.readdir( dir, { withFileTypes: true } );
for ( const file of files ) {
if ( file.isDirectory() ) {
yield* readAllFiles( path.join( dir, file.name ) );
} else {
yield path.join( dir, file.name );
}
}
}
async function toArray( asyncIterator ) {
const arr = [];
for await ( const i of asyncIterator ) arr.push( i );
return arr;
}If the script works out, I'll file a PR. It is supposed to be located in |
|
I split the changes of this PR into two. |
|
im going to try this. |
Thanks for looking into this 🙏 The size is a problem though, 3.7MB is more space than the AIs can handle. I'm trying to look for ways to work around this. Someone on twitter also shared this npm module: https://www.npmjs.com/package/jsdoc-to-markdown Edit: Svelte's approach seems interesting... |
Yeah, that sounds good to me. However, after working on 49f25c6 today, I'm pretty sure we can keep the |
3 participants
Related issue: #30748
Description
The PR is a first attempt to implement a client-side redirect from the old to the new documentation.
Since the old documentation is iFrame based, I've realized there is a single spot for implementing a redirect in
index.html.The build path of the new docs has been updated. The docs are not built into
/docs_new/<package>/<version>anymore but just/docs_new. That makes the setup a bit simpler.