📓 Documentation request | GitHub-Pages-Style Theory Manual

[Wesley-Jakob-Gilbert]

Document & Version:
FEBio Theory Manual 4.12

Section:
All sections

Request/Report:
I've been working through the FEBio documentation while learning the theory and codebase, and the biggest friction point has been page navigation. There is no "Next page" / "Previous page" control — you have to manually click each link in the sidebar to move through sequential sections. This makes reading longer guides (theory, user manual) harder than it needs to be.

I see there's a modern documentation format for the in-development FEBio Feature Manual through GitHub pages.

Could you also set up a modern static documentation site hosted on GitHub Pages, generated from Markdown in this repo and deployed via GitHub Actions for the other manuals? This would give us modern, automatic Next / Previous page navigation and a generally more ergonomic theory documentation.

Thanks for maintaining FEBio. It's a fantastic tool and I'd love to help in any way.

Theory Manual:

[SteveMaas1978]

Hi @Wesley-Jakob-Gilbert

Thanks for your suggestions. We definitely would like to update and modernize our online manuals, but given the size of our manuals, the user and theory manuals in particular, it is not trivial to make the changes you suggested. The FEBio Feature Manual is a first big step to move to a more modern approach using markdown+MkDocs, but that took a relatively long time to put together as it required copying sections out of our Lyx documents into markdown, often reformatting headings, text, and equations.
So we remain committed to providing up-to-date and modern documentation, but given our small software development team, the kind of changes you would like to see would have to wait until time permits.
It sounds like you are interested in contributing. Would that include contributing to the online documentation? If so, I'd love to hear your ideas on how we move this forward. In case it's helpful, please take a look at how we are managing the FEBio Feature Manual in the https://github.com/febiosoftware/febio-feature-manual repo. Look forward to hearing your thoughts!

Best,

Steve

[Wesley-Jakob-Gilbert]

Hi @Wesley-Jakob-Gilbert

Thanks for your suggestions. We definitely would like to update and modernize our online manuals, but given the size of our manuals, the user and theory manuals in particular, it is not trivial to make the changes you suggested. The FEBio Feature Manual is a first big step to move to a more modern approach using markdown+MkDocs, but that took a relatively long time to put together as it required copying sections out of our Lyx documents into markdown, often reformatting headings, text, and equations. So we remain committed to providing up-to-date and modern documentation, but given our small software development team, the kind of changes you would like to see would have to wait until time permits. It sounds like you are interested in contributing. Would that include contributing to the online documentation? If so, I'd love to hear your ideas on how we move this forward. In case it's helpful, please take a look at how we are managing the FEBio Feature Manual in the https://github.com/febiosoftware/febio-feature-manual repo. Look forward to hearing your thoughts!

Best,

Steve

Hello @SteveMaas1978,

Thanks for the reply. Yes, I am interested in contributing! I'd like to contribute to this request if helpful for y'all. Given the scope of the manuals, I'd suggest starting small with just Chapter 2: Continuum Mechanics in the Theory Manual as a pilot, following the same pattern converting Lyx -> markdown/MKDocs + Material + MathJax in the same style/theme as the Feature manual for homogeneity. That chapter is fairly equation dense, so I think it would be a good test of how well the conversion works, but I'd be happy to hear y'all's opinion of starting point. If the maintainers are happy with the pilot, we continue chapter-by-chapter and then continue to the User Manual and/or any other manuals.

If you'd like me to move forward with this pilot, I would be glad to. I estimate I could finish this pilot within a couple weeks. Before I do, is there an existing script y'all use to handle conversion from Lyx to markdown or is it all by-hand?

Best regards,
Wes

[SteveMaas1978]

Hi Wes,

That's great to hear! Please feel free to take a crack at it. I agree just doing a single chapter is the best place to start for now.

Before creating the feature-manual, I looked into some way to easily convert Lyx to markdown but didn't really come up with anything. I ended up doing it all by hand. Now, with AI agents, there is likely a way to speed this process up.

By the way, are you okay if I move this thread to a Discussion? Given where the conversation is going, I think that's a better place for it than in Issues.

I look forward to seeing your work and already a big thanks in advance for your willingness to contribute!

Best,

Steve

[Wesley-Jakob-Gilbert]

Hello Steve,

Great! I will start tonight. Yes, feel free to move this thread to a Discussion.

Best regards,
Wes

[Wesley-Jakob-Gilbert]

Hello @SteveMaas1978,

Here is a quick update on my progress. See https://wesley-jakob-gilbert.github.io/FEBio-theory-manual/ and https://github.com/Wesley-Jakob-Gilbert/FEBio-theory-manual. I created a LyX to markdown converter that seems to have successfully converted the chapter's source material for MkDocs. I'm still working through the manual to iron out any kinks and ensure accuracy. Please let me know if you have any suggestions or want to see something different before I finish QA and transfer ownership of the repo.

[Wesley-Jakob-Gilbert]

Hello @SteveMaas1978,

I've finished an initial draft of the entire manual. Please see https://wesley-jakob-gilbert.github.io/FEBio-theory-manual/. I'm continuing to make small edits here and there, but the bulk of the work is done. Please let me know how you wish to move forward from here.

This may be a future change, but I might also suggest combining the user, theory and other manuals into a single repository and GitHub pages website where each manual is its own tab at the top. Just something to consider.

Thanks again for giving me the opportunity to contribute.