📓 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.

[SteveMaas1978]

Hi @Wesley-Jakob-Gilbert,

This is great! I took a look at it, and it looks like you did more than just one chapter :). That's fantastic! The tool to convert Lyx to md that you created will also be useful moving forward. Thanks for working on all of this!

I'm going to share your work with the rest of the team here on our Friday meeting and let you know their thoughts. I definitely would love to move forward with this and use the MkDocs+Material site as the main documentation source.

Just a few additional thoughts as they popped up in my head:

1. It looks like the conversion from Lyx to md went fairly well with only a few issues. If there are things we can modify in the Lyx document to prevent future issues, let us know.
2. For the user manual, we have some other plans. With the feature manual that now lists all the features of FEBio, the user manual will probably be stripped down to a more general discussion of the input file format. I wouldn't spend any time on the user manual at the moment.
3. I like the idea of moving all documentation to a single site where you select the specific manual from a tab bar at the top. To do that, it might be better to move the documentation out of FEBio and into a separate GitHub repo, where we can also host all the scripts for generating the site.
4. It does look like MkDocs is going a different direction with MkDocs2. Do you have any thoughts on whether it might be best to switch to MkDocs2 or for now stick with MkDocs+Material?

Let me know if you have any additional thoughts or comments. I'll be back in touch once I had an opportunity to discuss this with the group here. In any case, thanks again for your willingness to contribute and the work you've done so far!

Best,

Steve

[SteveMaas1978]

Hi Wes,

I shared your work with the rest of the FEBio team, and everyone was really impressed. Converting the entire Theory Manual into a modern, easy-to-navigate site in such a short time is no small thing.

I think we’re all in agreement that we’d love to see this project continue. We’d also be very happy to keep you involved if that’s something you’re interested in, but of course there’s absolutely no pressure.

If you are interested in staying involved, I’m curious to hear your thoughts on where you’d like to take this, and what a good way forward might look like.

Thanks,

Steve

[Wesley-Jakob-Gilbert]

Hello @SteveMaas1978

Fantastic! I'm glad there was such a positive reaction and that I could make a helpful contribution. Thank you.

Yes, I'd be very glad to stay involved. I wasn't aware of the MKDocs2 migration until I did some research just now. It seems there's some volatility from both MKDocs and Material. Material is end-of-life this November and MKDocs2 is significantly different.

I personally think the best solution is to stick with Material for MKDocs for the next 6-12 months and then revisit. By then, hopefully the ecosystem becomes stable again, but what we are currently building is stable, works well now with all necessary functionality and without any extra complexity. Have you heard about Zensical? It is a new project by the developers of Material that they plan to have replace both MKDocs and Material in one backwards-compatible ecosystem. If that is true, we may be able to easily migrate to Zensical without too much effort in about 6 months when we revisit.

If you'd like me to continue working on this, I'm happy to iron out the existing Theory Manual and add some other manuals, starting with the Studio manual. My vision for this restructuring long-term would be to link to one GitHub pages site for all manuals in the FEBio knowledgebase.

Let me know if you agree or have any other thoughts before I continue consolidating the other manuals in one GitHub pages site. And also let me know if/when you would like me to transfer ownership to febiosoftware.

Best,
Wes

[SteveMaas1978]

Hi Wes,

Your plan sounds good to me.

I think it makes sense to transfer ownership to febiosoftware. I can give you the necessary permissions to work on it there. I'm not sure if you can change the name from "FEBio-Theory-Manual" to something more general, like "FEBio-Documentation" or something, when you transfer. We can also create a new repo, and then you can start fresh, copying your files to this new repo. I've never had to transfer ownership of a repo, so not sure what is easier. Let me know your thoughts.

Once we have the repo set up, we can copy all the lyx files in there (FEBio TM, FEBio UM, and FBS UM). We may also want to look whether we can move the febio-feature-manual to this new repo. That one does not start from a lyx file, but it would be nice to get all manuals in one place.

Regarding future migration, I have heard of Zensical and that might indeed be the better target. But I agree, we can revisit later.

Best,

Steve

[Wesley-Jakob-Gilbert]

Hello Steve,

Since I don't have repo creation access in the febiosoftware organization, I think it's easiest if you make a blank repo called FEBio-Documentation or similar and add me as a collaborator or maintainer. I can then push everything I have and continue working.

I can also add the febio-feature-manual as is by just copying the markdown and supporting MKDocs configuration files.

Let me know if that works for you and I'll get to work :)

Best,
Wes

[SteveMaas1978]

Hi Wes,

I created a new repo https://github.com/febiosoftware/febio-docs/ and invited you as a contributor. You should have write access and be able to add and push to this repo. Let me know if you run into any issues.

Best,

Steve

[Wesley-Jakob-Gilbert]

Hello Steve,

I've pushed the code into the febio-docs repo. Please change the following settings to allow github pages deployment:

1. Settings -> Actions -> General -> "Actions Permissions" set to allowed for this repo
2. Settings -> Actions -> General -> "Workflow Permissions" set to read and write
3. Settings -> Pages -> "Build and Deployment" -> Source to "Deploy from branch" and branch: gh-pages / /(root)

or just copy the settings from the febio-feature-manual repo.

Thanks!
-Wes