Hi Ramin, Thanks for picking this up, +1. Having a nicer UX for docs has been a long standing wish and makes sense. Some suggestions and questions:
1. Also publish each function page as plain Markdown, plus an llms.txt that indexes them. Hugo supports extra output formats, so this should be cheap. 2. Keep the function data in YAML, with one field per section (syntax, arguments, returns, examples) instead of a free-form description. A single template then renders every page with the same sections, as HTML and Markdown. 3. We have built-in functions with no examples. Do you plan to add some examples for those as part of this or will the pages just hide the examples session? Kind regards, Gustavo On Wed, 28 Oct 2026 at 14:57, Ramin Gharib <[email protected]> wrote: > Hi all, > > I'd like to restructure the built-in functions page [1]. It lists 306 > functions and operators as table rows on a single page, each with a > free-form description. Arguments, return values, NULL behavior and errors > are hard to find. > > The proposal picks up FLINK-23804 [2]: > - Each function gets its own page with the same sections: syntax for SQL > and the Table API, arguments, returns, usage notes and examples. > - The sidebar groups the function pages by category, and each category > folds open and closed. > > The screenshots [3] show REGEXP_EXTRACT and the sidebar in the new layout, > built locally with the current docs theme. > > I'd move one category per PR. Moving the existing entries is mostly > mechanical, so I'd use AI assistance and fill in the AI disclosure in the > PR template. > > I would be interested in your feedback on this idea. > > Cheers, > Ramin > > [1] > > https://nightlies.apache.org/flink/flink-docs-release-2.4/docs/sql/functions/built-in-functions/ > [2] https://issues.apache.org/jira/browse/FLINK-23804 > [3] > https://drive.google.com/drive/folders/123rKBt0ESz5Wn5VSlCcQF3hxJuwtf3Q9 >
