This is a set of stylesheets, templates, and code for Asciidoctor and Antora rendered documentation to give it a uniform look and feel befitting the quality of Boost.
Example of integration into a doc Jamfile:
html mp11.html : mp11.adoc
: <use>/boost/boostlook//boostlook
<dependency>mp11-docinfo-footer.html
;
Noto font files are covered under the Open Font License:
https://fonts.google.com/noto/use
BoostLook includes a live preview feature to streamline local development and review of AsciiDoc documentation. This allows for automatic rendering and real-time browser preview of changes made to specimen.adoc
and boostlook.css
files.
The preview functionality is handled by a Ruby script (boostlook_preview.rb
). This script monitors AsciiDoc, HTML, and CSS files for changes, automatically rebuilding and opening the rendered HTML in your default web browser.
Ensure the following dependencies are installed:
- Ruby (>= 2.7 recommended)
- Asciidoctor – Install via
gem install asciidoctor
- Listen Gem – Install via
gem install listen
- Boost.Build (b2) – Required for builds invoked by the script. Ensure it is installed and available in your system's PATH.
-
Install Ruby and Required Gems:
- Ensure Ruby is installed on your system. You can check by running:
If Ruby is not installed, follow the instructions on ruby-lang.org to install it.
ruby -v
- Install Asciidoctor:
gem install asciidoctor
- Install the Listen gem:
gem install listen
- Ensure Ruby is installed on your system. You can check by running:
-
Install Boost.Build (b2):
- Follow the instructions on the Boost.Build website to install
b2
. - Ensure
b2
is available in your system's PATH by running:which b2
- Follow the instructions on the Boost.Build website to install
-
Locate Specimen AsciiDoc File:
- Place your AsciiDoc files in the
doc
directory. The default file isdoc/specimen.adoc
. - The default file structure should include:
/boostlook ├── doc │ └── specimen.adoc <-- │ └── ... ├── boostlook.css └── boostlook_preview.rb └── boostlook.rb └── ...
Navigate to the project directory:
cd /path/to/boostlook
Run the preview script:
- Ensure you're in the root folder
ruby boostlook_preview.rb
Edit and Preview:
- Edit your AsciiDoc (specimen.adoc) or CSS (boostlook.css) files.
- The script will automatically detect changes and rebuild the documentation.
- Refresh the browser to see changes.
Refresh Your Browser to view changes.
-
Script Not Running:
- Ensure all prerequisites are installed correctly.
- Check for any error messages in the terminal and resolve them accordingly.
-
Changes Not Reflecting:
- Ensure the files being edited are within the monitored directories (
doc
and root directory). - Verify that the browser is refreshing automatically or manually refresh the browser.
- Ensure the files being edited are within the monitored directories (
-
Boost.Build (b2) Not Found:
- Ensure
b2
is installed and available in your system's PATH. - Run
which b2
to verify its availability.
- Ensure
boostlook's People
boostlook's Issues
preview URLs in the README
The README needs to provide the URLs where the master and develop branch boostlook can be previewed
Phase 3 work on boostlook UI
Continue with working on boostbookV2 integration issues
fix styling with .qbk pages as well
Phase 1 work on boostlook UI
This is a placeholder for the first batch of work on the boostlook UI, and will likely encompass wide ranging fixes to font sizes, spacing and such. Details should be provided in the PR.
As PR are approved, new, more specific tasks will follow.
css font paths don't look right
They seem to have different paths. This path for example, does it even exist?
https://github.com/cppalliance/boostlook/blob/develop/boostlook.css#L73
Change hide/show button for sidebar
convert hide/show button in sidebar to something that is static to the side, rather than moving when open and closed
align code styling between doc types
styling for code blocks inconsistent between boostbook, antora, asciidoc etc.
Each styling pattern will need to be decoded and align so they match.
Change font name
in boostlook some fonts are not loading, and the em tag is using an algorythmic italic
Please update font name "Noto Sans Italic" to "Noto Sans Display" so it uses the italic font as part of the normal font.
Also check that in the standalone viewer that the fonts are being loaded
Horizontal overflow with scrollbar in big mrdocs-generated member tables
I'm seeing the behavior in this page: https://anarthal.github.io/mysql-mrdocs-v2/mysql/reference/boost/mysql/common_server_errc.html
This is using the current master UI bundle.
If there is any more info you need to investigate this, please let me know.
Update GitHub Action to Trigger Action on website-v2-docs
Add an action that triggers a workflow in the website-v2-docs repository whenever the develop branch is updated. This ensures the latest boostlook.css is fetched automatically, keeping the website documentation consistently up-to-date with the most recent styles and changes.
collapse nav UI should not move when toggled
feature: preview tool
It would be nice to have a command line tool which, when invoked, renders the specified asciidoc input file into HTML using boostlook, and opens the result in a browser window.
fixed antora menu on mobile
Prevent hyphenation of entity links generated by MrDocs
Links to C++ entities are currently subject to be split across several lines through hyphenation. For example:
Live: https://anarthal.github.io/mysql-mrdocs-v1/mysql/reference/boost/mysql/sequence.html (please ignore the other glitches, they're in the process of being solved).
Breaking the name of a C++ entity looks weird, as it's not legal in C++. Entity names should be limited in number of characters, so it should be safe to apply whatever CSS property is required to make the word be entirely on the next line.
TOC Styling updates
Code Highlighting sample sheet
There needs to be a sample specimen doc with different code blocks using the different code types used within the projects as a basic standard for how a block should look when using highlightjs, in both light and dark mode
Will also need a way to create a gulp preview
"More" links generated by MrDocs in overload pages have too much vertical spacing
"More" links generated by MrDocs reference the entities declared above them. The current spacing makes them look like they refer to the entities below them.
Live example: https://anarthal.github.io/mysql-mrdocs-v1/mysql/reference/boost/mysql/any_connection/async_close.html
Rendered as:
Create adoc for boostlook testing
Boostlook needs a CI setup where on PR or push to master/develop it renders the sample.adoc into HTML and publishes it, so at any time we can look at the master or develop rendering and know what the latest style looks like.
../../../b2 cxxstd=20 toolset=gcc-13 define=BOOST_CHARCONV_RUN_BENCHMARKS STL_benchmark linkflags="-lfmt" -a release .
needs to go into a code block and we want to see that in the sample.adocThis sample should include all options used in the adoc.
Replace Rouge with highlight.js for code styling
Replace the current Rogue syntax highlighter with highlight.js.
Note:
This affects only libraries that use asciidoc + boostlookprocess for rebuilding all effective docs when boostbook changes
When someone renders asciidoctor docs, the boostlook.css file contents need to be inserted. This is accomplished by passing the right command line argument to the asciidoc tool, as shown here:
https://github.com/vinniefalco/mp11/blob/develop/doc/Jamfile#L13When someone renders antora docs, the same thing should happen. The boostlook.css file contents should be inserted into the resulting HTML
The website injects the header when it serves documentation. And we should modify the asciidoc and antora build process so that the resulting HTML has a hint to where the website should insert the header
Boostlook support and updates of antora docs
Multiple antora issues, fix in boostlook where possible:
- Sidebar fonts should be condensed and vertically spaced more closely.
- Sidebar links- remove underline, font text black, hover make blue (from standard colors)
- Sidebar selected item - have carat text to item, without indenting item
- Breadcrumbs - condensed font, move home icon from right to the beginning of breadcrumb.
- Breadcrumbs missing on mobile view
- Add "printable version"
- Code syntax highlighting needed
- Tables need boostlook appearance
heading oddity
Phase 4 UI
The specific goal for this phase has several components:
- we want to refactor font related tags and classes into single tag level classes that apply the same everywhere, for example taking:
.boostlook h4 { font-size: 130%; } .boostlook .antora h4 { font-size: 125%; font-weight: bold; margin-left: 1rem; }
should be :
.boostlook h4 { font-size: 130%; font-weight: bold; } .boostlook .antora h4 { margin-left: 1rem; }
move the font related elements together and the specifics on formatting for a specific case separately. This will simplify the code and insure that fonts will display the same under any doc type.
-
Any references to font weights should be number values based on the variable fonts, so I'd like to start with 500 and go bolder at a +50 increments
-
Be sure all border-radius attributes are removed or set to zero.
When boostlook is moved to stage, use that to trigger moving boostlook to website-v2 develop
To avoid the issues we have had with updating boostlook. instead of the trigger to move from master to master, we would move from develop to develop, and then the current boostlook would go to website-v2 master during the weekly merge, avoiding any other issues.
@sdarwin this is basically what we discussed, let me know if you have additional thoughts or concerns.
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
- Place your AsciiDoc files in the